Shareware Super Platinum 8

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Super Platinum 8 / Shareware Super Platinum 8.iso / mac / PROGTOOL / DOCZ16.ZIP;1 / DOCZ.LIF / DOCZ16.DOC < prev next >

Wrap

Text File | 1994-03-02 | 263.6 KB | 8,977 lines

DOCZ(tm) An Automated Code Documentation System Version 1.6 User Manual Software Toolz, Inc. 8030 Pooles Mill Drive Ball Ground, Georgia 30107 (404) 889-8264 FAX (404) 887-5960 Internet: software@toolz.atl.ga.us Special contributions and inspiration provided by: Roger D. Wood Loren L. Brumbaugh, Jr. Chip Owen Karl Klingman The text permutation algorithm was developed and contributed to the DOCZ System by: Paul D. Anderson The DOCZ System was designed and written by: Todd Merriman Trademarks: DOCZ is a trademark of Software Toolz, Inc. MSDOS and XENIX are trademarks of Microsoft IBM-PC, RS6000 and PCDOS are trademarks of The International Business Machines Corporation DEC, DEC/CMS, VAX, and VMS are trademarks of Digital Equipment Corporation 8086 is a trademark of Intel Corporation UNIX is a trademark of AT&T BRIEF is a trademark of UnderWare, Inc CTIX is a trademark of Convergent Technologies AViiON and DG/UX are trademarks of Data General SUN and SPARC are trademarks of Sun Microsystems Dbase is a trademark of Ashton-Tate SCO is a trademark of Santa Cruz Operation The installation program used to install the MSDOS version of the DOCZ System, INSTALL, is licensed software provided by Knowledge Dynamics Corporation, Highway Contract 4 Box 185-H, Canyon Lake, Texas 78133-3508 (USA), 1-512-964- 3994. INSTALL is Copyright 1987-1989 by Knowledge Dynamics Corporation which reserves all copyright protection world- wide. INSTALL is provided to you for the exclusive purpose of installing the MSDOS version of the DOCZ System. User Manual Revision 33275 DOCZ Version 1.6 User Manual 2 NOTICE Be informed that this manual and the associated computer programs are protected by Public Laws 94-553 and 96-517 of the 94th and 96th Congress. Any person who infringes a copyright for commercial advantage or financial gain will be subject to federal criminal prosecution. DISCLAIMER This software is licensed (not sold). It is licensed to sublicensees, including end-users without express or implied warranties of any kind. Software Toolz, Inc. makes no warranties with respect to this manual, or with respect to the software described in this manual, its quality, performance, merchantability, or fitness for any particular purpose or noninfringement of patents, copyrights or other proprietary rights of others. Software Toolz software is sold as is. The entire risk as to its quality and performance is with the buyer (and not Software Toolz, Inc., its distributor, or its retailer), and the buyer assumes the entire cost of all necessary servicing, repair, or correction and any incidental or consequential damages. In no event will Software Toolz, Inc. be liable for direct, indirect, incidental, or consequential damages resulting from any defect in the software, even if Software Toolz has been advised of the possibility of such damages. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. Further, Software Toolz, Inc. reserves the right to revise this publication without obligation to notify any person of such revisions. Information in this publication does not represent a commitment on the part of Software Toolz, Inc.. Copyright 1986, Thomas C. (Todd) Merriman, d/b/a Future Communications, Atlanta, Georgia Copyright 1990, Software Toolz, Inc., Atlanta, Georgia 3 CONTENTS Building a New DOCZ Documentation Library ...........9 CONCEPTS .................................................11 What is DOCZ? .......................................11 What does DOCZ Do? ..................................12 Major Functions .....................................12 What is a Library? ..................................14 What is a Module? ...................................14 Directories .........................................15 The DOCZ Programs ...................................17 Command Line Arguments ..............................19 Conventions Used in this Document ...................20 Program Operation Conventions .......................21 File Formats ........................................21 Miscellaneous Conventions ...........................23 Date Format .........................................23 Naming Conventions ..................................25 Architecture ........................................25 FORMATTING SOURCE CODE ...................................27 The Documentation Header ............................27 The Parameters for Documentation Headers ............29 Parameter Summary ...................................34 Building Documentation Libraries ....................37 Full Library Documentation ..........................41 Printing ............................................42 The Library Introduction ............................42 Revision/Fix Notices ................................43 Change Notices ......................................45 Library Summary .....................................45 Single Module Documentation .........................47 The Configuration File ..............................49 The Printer Interface ...............................49 Multiple Language Support ...........................53 Specifying a Comment String Mask ....................53 Specifying Comment String Masks for File Extensions ..........................................54 Transaction Logging .................................55 Alternate Directories and Version Control ...........57 MSDOS Username ......................................59 Variable TAB Expansion ..............................59 Specifying Command Line Options .....................60 Option Summary ......................................61 Dumping the Documentation Index .....................63 Displaying Modules Modified Since a Date ............63 Displaying Modules Introduced Since a Date ..........63 Deleting a Module ...................................64 Searching for a Module ..............................64 Feeding the Documentation Index to Other Programs ...64 Reorganizing Documentation Index Files ..............65 DOC .................................................67 DOC Examples ...................................68 DOCXL ...............................................69 DOCXL Examples .................................71 5 CONTENTS DOCXLU ..............................................72 DOCXLU Examples ................................76 DOCHBLD .............................................77 DOCHELP .............................................79 DOCXLED .............................................81 DOCGET ..............................................85 DOCLIS ..............................................86 DOCLOG ..............................................88 DOCMAN ..............................................90 DOCLEARN ............................................91 PSET ................................................93 PCODE ...............................................97 CALCDATE ............................................99 REFORMAT ............................................100 FILLS ...............................................102 DETAB ...............................................103 RETAB ...............................................104 ERROR MESSAGES ...........................................105 Directory Layout ....................................117 Cross-Platform Development ..........................118 Using DOCZ WIthout Source Code ......................122 Building a Documentation Library ....................127 strmcpy.c - C Language ..............................128 strmcpy.asm - 8086 Assembly .........................128 strmcpy.mar - VAX11 Assembly ........................128 move.bat - MSDOS Batch File .........................128 fake.bas - BASIC Function ...........................128 upcase.for - FORTRAN Function .......................128 cmdline.pas - Pascal Function .......................128 mailfile.com - DCL Command File .....................128 cp_r.sh - Bourne Shell Script .......................128 macro.h - C Language Macro ..........................128 gtsa.prg - Dbase Language ...........................128 frank.prl - Perl Language ...........................129 DOCREVS.COM - DOCZ Automation .......................129 docrevs.sh - DOCZ Automation ........................129 DOCSTASH.COM - DOCZ Automation ......................129 docstash - DOCZ Automation ..........................129 A Sample DOCZ Library ...............................130 Documentation Index Record Format ...................131 Development Language ................................131 Version Control Software Interface ..................132 Standard Error ......................................132 8.5 x 11 Documentation Size .........................132 Case in Module and Library Names ....................132 Some Implementation Requirements ....................133 Basic Installation ..................................141 Re-installation/Update ..............................141 Enabling Extended DOCZ Features .....................142 Examples and Support Files .....................143 MSDOS VERSION .......................................144 MSDOS Version Minimum Requirements .............144 Getting Started with the MSDOS Version .........144 6 CONTENTS MSDOS Version Installation Procedure ...........144 Files in a Working DOCZ System .................145 VMS VERSION .........................................147 VMS Version Minimum Requirements ...............147 Getting Started with the VMS Version ...........147 VMS Version Installation Procedure .............147 Files in a Working DOCZ System .................149 UNIX VERSION ........................................151 UNIX Version Minimum Requirements ..............151 Getting Started with the UNIX Version ..........151 UNIX Version Installation Procedure ............151 Files in a Working DOCZ System .................153 ................................ INDEX ....................155 7 Getting Started Quickly! Building a New DOCZ Documentation Library (1) The installation procedure will have created a command file in the DOCREF directory called: Unix: $DOCREF/docz_sym MSDOS: %DOCREF%/DOCZ_SYM.BAT VMS: SYS$MANAGER:DOCZ_LOGIN.COM This command file will create the required DOCSRC and DOCREF environment symbols for use by DOCZ. If you have not already, run this command file so that DOCZ programs will be able to find the files in the DOCSRC and DOCREF directories (the Unix command file should be dot executed). The MSDOS installation procedure optionally modifies AUTOEXEC.BAT to define the required symbols. Select a name for your library. The name may have, but (2) does not need to have a physical relationship to any object library or group of programs. The name should be up to 11 characters in length, and should contain no punctuation. Create a sub-directory to the DOCSRC directory (DOCSRC (3) was created during installation), with a name the same as the name you have chosen for your library (upper case in Unix). (4) Select the modules to be contained in the documentation library. Modules are either subroutine names (when documenting object libraries) or program names (when documenting program or command file libraries). They may also be object names when using an object-oriented language. Edit the Documentation Header in your source code for (5) each module you want to document. Each source file may contain one or many modules, and there will be one DOCZ Documentation Header for each module in a source file. (6) Move the source files to your new DOCSRC subdirectory. (7) Run DOCXL or DOCLIS to add the module to the Documentation Index (see the DOCXL or DOCLIS program reference). DOCLIS will "mass-load" the documentation library with one invocation. DOCXL will add each module one at a time. Run DOC on the library to test the documentation (see (8) the DOC program reference). 9 Getting Started Quickly! (9) Run DOCHBLD to build an on-line help library (see the DOCHBLD program reference). (10) Use the manual section, "SELECTING OPTIONS" to enhance and modify your DOCZ environment. If you are adapting DOCZ to a pre-existing development environment, this manual section will show you how to override the installation defaults used by DOCZ and set up an environment more suitable to your current environment. For instance, your source code does not necessarily have to be stored in a sub-directory with a name the same as the documentation library name. Use the manual section, "PUBLISHING DOCUMENTATION" to (11) learn how to automate Revision Notices and publish other types of DOCZ reports. The source files for many examples in various languages were deposited in the DOCSRC directory by the installation procedure. In addition, the sample documentation library called CSUB may have been built from sample sources at DOCZ installation time, if that option was selected by the installer. The bldocz command file has been provided in the DOCSRC directory to demonstrate how CSUB was built. 10 CONCEPTS What is DOCZ? Have you ever wished that you could fully document subroutine libraries and programs such that they could be used by everyone in your software development environment? DOCZ is a software tool that automates that kind of code documentation. Software developers know that a high degree of efficiency is required in today's software market to compete, and one means of achieving high efficiency is by reusing code. The DOCZ System provides the means to document code to make it easy to reuse by many in a development environment. The concept is simple: the code documentation is contained in the source code itself. The documentation is completed by the software developer whenever a new module is introduced. A good development environment is one that facilitates the sharing of resources between software developers. The DOCZ System automates the entire process of managing the documentation for shareable code. DOCZ consists of a group programs that extracts code documentation from the source code and composes it into print image. 11 CONCEPTS What does DOCZ Do? S Allows documentation and source code to be contained in a single file S Supplies the mechanism for providing documentation of code to be used by other software developers S Works with 'C', Assembly, Pascal, COBOL, FORTRAN, BASIC and command-language-interpreter languages. Theoretically, DOCZ may be used with any language for which the source is stored in text S Allows a complete documentation set to be produced immediately on demand, and the documentation includes an index and quick-reference, as well as detailed module documentation S Uses printer features to enhance output format of the documentation S Makes the sharing of resources in large development groups much easier S Takes the drudgery out of code documentation and makes it easy for the programmer to produce polished documentation S Simplifies the publishing of revision, change, introduction and fix notices S Provides on-line documentation for library modules and prototypes for selected editors S Automatically retrieves source files via source code version control systems (SCCS under UNIX, and under VMS) CMS S Provides for a cross-platform development environment and identical functionality with Unix System V, VMS, and MSDOS (including PC-networks) Major Functions S Adding or updating a module S Producing the library documentation S Producing revision or fix notices S Producing documentation for recently changed modules 12 CONCEPTS S Maintaining the Documentation Index S Building and using on-line help libraries 13 CONCEPTS What is a Library? A DOCZ "library" is a name. The name may have, but does not need to have a physical relationship to any object library or group of programs. It designates a logical "group" of modules. You may have one or many Documentation Libraries. The name may be up to 11 characters in length, and should contain no punctuation. What is a Module? A DOCZ "module" is a name. Modules are either subroutine names (when documenting object libraries) or program names (when documenting program or command file libraries). They may also be object names when using an object-oriented language. The name may be up to 31 characters in length, and naming should follow standard file and/or object module entry point naming conventions. 14 CONCEPTS Directories DOCZ documentation may refer to five directories on your system: (1) The Default Source Directory - DOCSRC Although source may be stored in any device or directory, the simplest approach is to use the default source directory (also known as the Documentation Source Directory). When no directory or device is specified in the Documentation Index, the DOC program will search for files in a subdirectory of the default source directory. In a large DOCZ installation, there could be many of these sub-directories. (2) The Documentation Reference Directory - DOCREF This directory is where DOCZ programs will search for the Documentation Index File, library documentation "introductions," and other DOCZ system reference files. See the installation documentation for more information. (3) The Documentation Data Directory - DOCDAT (VMS) This directory is used for certain reference data files used in DOCZ. In the MSDOS and UNIX versions, the "PATH" is searched for these files; consequently the Documentation Data Directory may be several physical directories. In the VMS version a directory must be set aside where these files can be located when any of the DOCZ programs run. There is only one of these directories on any VMS system, and it is pointed to by the DOCDAT logical name. (4) The Program Directory The directory where DOCZ executable images reside when you are using DOCZ. In the MSDOS and UNIX versions, the "PATH" is searched for these files. In the VMS version, the DOCZ programs are defined as DCL foreign commands, and their symbols point to the location of the executable image. (5) The Working Directory The default directory when you run any of DOCZ programs. 15 CONCEPTS Ideally, these five logical directories do not exist as the same single physical directory, although this is not generally prohibited by the DOCZ System (see INSTALLATION for more information). 16 CONCEPTS The DOCZ Programs DOC Generate module documentation DOCXL Add/update the Documentation Index DOCXLU Search and manage the Documentation Index DOCHBLD Generate an on-line library documentation help file DOCHELP Scan/display on-line help documentation DOCXLED Examine/search/modify the Documentation Index File DOCGET Extract a field from a documentation header DOCLIS Find all DOCZ modules in a source file DOCLOG Examine/search the log file DOCMAN On-line DOCZ User Manual DOCLEARN On-line DOCZ tutorial 17 CONVENTIONS Command Line Arguments S Whenever you see the angle bracket symbols (< and >) in a command line specification, they denote a required argument. S Whenever you see the square bracket symbols ([ and ]) in a command line specification, they denote an optional argument. S Command line prompts (d> for MSDOS and $ for VMS and UNIX) are not displayed in this documentation. Only the command line arguments typed by the user are displayed, to avoid confusion. S Generally, in all DOCZ programs, if no command line arguments are specified when the program is run, then a list of possible command line arguments is displayed as a reminder to the user. S The "switch character," the character recognized as a delimiter for command line options, is (by default) the slash ('/') character in MSDOS and VMS versions, and is the dash ('-') character in the UNIX version. This is consistent with the respective operating system conventions, but may be changed to any other character (such as '+') by defining the SWITCHAR symbol in the UNIX and MSDOS versions or the SWITCHAR logical name in the VMS version. This document will display command-line options with the '/' delimiter. Modifiers for command options are usually separated from the option specifier with an equals (=) sign. S Some DOCZ programs accept "ambiguous file names" (DOCLIS, for example). If a file specification is illustrated as "a.f.n.," the specification may be an "ambiguous file name." This means that the file specification may contain wildcard characters for multiple matches to file names. Wildcarding in DOCZ programs will conform to the operating system conventions ('%' and '*' in VMS, '?' and '*' in UNIX and MSDOS). DOCZ wildcards also provide the additional capability of specifying multiple paths in the ambiguous file name, as long as all specifications are contained in quotes so that they may be presented as a single argument to DOCZ programs. For example: "\DOCSRC\ULIB\*.pas \DOCSRC\UTIL\*.c" 19 CONVENTIONS Conventions Used in this Document S Program names are always illustrated in upper case but, in the UNIX version, are named in lower case. S Batch files (MSDOS), shell scripts (UNIX), and command files (VMS) are all referred to as "command files." 20 CONVENTIONS Program Operation Conventions S In UNIX DOCZ, program names are always in lower , while data and reference files are always in upper case. S All Software Toolz programs display a minor revision number that will be greater than 31000. This number is a Julian equivalent of the date on which the program was created. This is provided to determine exactly which version of a program is being run. The actual date on the file in the directory is meaningless. S DOCZ programs are not generally interactive, i.e. there is no prompt/response type operations. This convention is adopted to allow the user to more fully automate their documentation through the use of command files that can pass arguments to DOCZ programs. S DOCZ programs may return a value to the command- language interpreter that may be significant. For those DOCZ programs that do return a value, the actual value is operating system dependent: REFERENCE NAME UNIX/MSDOS VALUE VMS VALUE EXITNORMAL 0 1 EXITWARN 1 3 EXITBAD 255 4 For example: the DOCZ documentation specifies that the DOC program returns EXITBAD if it cannot open the Documentation Index File. For VMS, this means that $STATUS will be set to the value, 4. For MSDOS, this means that ERRORLEVEL will be set to 255. For UNIX, this means that $? will be set to 255. This will allow you to include references to DOCZ programs in command files, and command file program flow can be determined by the results of programs. File Formats A commonly used file format in DOCZ is the text data format. It is a text file format containing variable length records composed of variable length fields delimited with a comma. Records are delimited with an End-of-Line (which varies between operating systems). Fields that require the embedding of commas may be surrounded by either the double quote character or the apostrophe. If the double-quote must be embedded in the field, the apostrophe is used to surround 21 CONVENTIONS the field. If the apostrophe must be embedded in the field, the double-quote is used to surround the field. This file format has the advantages that it can be edited with a text editor, though it is not "print image." Record size is generally never fixed, and records are only as large as required. Most operating system sort utilities are made to operate on this type of file. The DOCXL program outputs this format for one of the reports it produces; ASCII Transport Files use this file format. 22 CONVENTIONS Miscellaneous Conventions Control keys are sometimes utilized in interactive DOCZ programs. Whenever a prompt or legend is displayed for control keys the carat character will precede the key to denote that it is to be entered as a control character. For example: ^C actually represents a control-C. The carat character is not used for input in any DOCZ program. The "Press" prompt denotes that only a single keystroke is required for input. The "Enter" prompt denotes that one or more keystrokes followed by a [RETURN] is required for input. Date Format Dates specified to DOCZ programs have a format that is specified by the user. The default date format is: MM/DD/YY which is the most common U.S. format. Leading zeroes are not required when the date is input but will be supplied when the date is displayed. Other formats for the date may be specified via an environment variable (or logical name in the VMS version), DATEFMT. If this variable is present when any of the DOCZ programs is run, it will be used to define the format of the date. The date format is specified using a string containing one or more of the characters, D, M, N, and/or Y, where: D represents the day number M represents the month number N represents the month name Y represents the year number 23 CONVENTIONS A date specification always has three fields: month, day, and year. The separator character specified in the date format will be used whenever the date is input or displayed: commonly used are '/' or '-', but any non-alphanumeric character may be used. For D and M, specifying two characters means that leading zeroes will be used. For Y, specifying YYYY means that the century will be used, as well as the year number; specifying YY means that only the year number will be used. When NNN is used to specify the month (instead of M or MM), the abbreviation for the month will be used (i.e. "JAN," "FEB," etc.). Case is ignored in date format specifiers. For example, the date format specifier may typically have (but is not limited to) the following formats: D-NNN-YYYY 1-MAY-1987 MM/DD/YY 05/01/87 DD/MM/YY 01/05/87 M/D/Y 1/5/87 MM-DD-YY 05-01-87 D-M-Y 1-5-87 MM/DD/YYYY 05/01/1987 When a date is to be specified to a program, the month, day, and year must all be specified. Many DOCZ programs allow defaulting to the current date (see the documentation for the individual programs). The following examples illustrate the definition of the date format: VMS $ DEFINE/PROCESS DATEFMT D-NNN-YYYY MSDOS SET DATEFMT=D-NNN-YYYY UNIX DATEFMT=D-NNN-YYYY export DATEFMT Note that once the date format is specified on your system, it cannot be easily changed due to the fact that revision and fix dates are imbedded in the source files in the required format. 24 CONVENTIONS Naming Conventions S Program and function documentation is grouped in logical "libraries." These libraries are named and may correspond to names of function libraries on the system. S The maximum length of a library name is eleven characters, and it is mapped to upper case. S Module names are restricted to thirty-one characters, and they are mapped to upper case. S The maximum length of a file specification (including the directory path) is: MSDOS: 87 characters VMS: 127 characters UNIX: 127 characters Case is preserved in path and file names (although it is ignored by MSDOS and VMS). S Limits are set on name lengths to minimize the size of the Documentation Index File. Architecture DOCZ maintains a Documentation Index File containing an entry for each module documented with the DOCZ System. It is a reference file maintained independently from any source code, and it contains the following information for each module in the DOCZ System: (1) Library name (2) Module name (3) Source file name 25 CONVENTIONS The "libraries" may contain programs, command files, or functions (referred to as "modules" in this manual). The source files may contain a program, a function, or many functions. Even macros that are usually contained in include files may be documented by DOCZ. Each module contained in a file must have a documentation header, which contains documentation components, delimited by "parameters," that will be extracted by the DOCZ programs. There is no limit on the number of library names used. There is one record per module in the Documentation Index File, and records may be marked for deletion to be reclaimed on the next add. There may be one or more modules in each source file. The (optional) Configuration File is used by all of the DOCZ programs to select options. See the section on "SELECTING OPTIONS." 26 FORMATTING SOURCE CODE The Documentation Header The Documentation Header has the general form: .<parameter> <arguments> This is a list of currently implemented parameters: .MODULE .LIBRARY .TYPE .DESCRIPTION .ARGUMENTS .NARRATIVE .APPLICATION .SYSTEM .AUTHOR .REVISION .FIXES .CAUTION .OVERHEAD .COMMENTS .RETURNS .LANGUAGE .EXAMPLE .SEE_ALSO .INCLUDES .NOTICE .LSE .REFERENCES .CONVENTIONS .PAGE .ERRORS .ENDOC Each of the elements in the documentation header is a parameter that has arguments (although no arguments are shown in the above outline). DOCZ programs scan this header and extract the arguments associated with the parameters, and reformat the arguments into a usable format. Some parameters are required, and others are optional. Some may appear only once, and others may occur many times. The documentation parameters are unique identifiers delimited with a period in the first column on the page (except when using a "comment string mask" with languages that require such). Only the first three characters of the parameters are scanned, but you should include the entire word for clarity. 27 FORMATTING SOURCE CODE Documentation text may appear on the same line as, or any line following the parameters, except for .MODULE and .LIBRARY names and the .REVISION or .FIXES date: in these four cases, the arguments must occur on the same line. Case is ignored in module name, library name, type description, application keyword, and operating system. For clarity, the text of your arguments to the parameters should be indented as the text will not be reformatted for the documentation. TAB characters may be used for indention, and they will be expanded to eight spaces by the DOCZ programs. Multiple modules may be contained in one source file, and each will have a documentation heading. Do not specify a delimiter without an argument (except for .ENDOC). The only parameters that are position dependent are .MODULE (starts the header) and .ENDOC (ends the header). Any code outside the documentation header is completely ignored by the DOCZ programs. Validation of required fields is done by the DOC program when it is generating output documentation. The Source Code Examples section of this manual displays a few documentation headers for some popular languages. A description of all documentation parameters and their options is described in "The Parameters for Documentation Headers." 28 FORMATTING SOURCE CODE The Parameters for Documentation Headers As illustrated in the following descriptions of parameter usage, the parameters are described as: OPTIONAL parameters do not have to be included in the DOCZ Header REQUIRED parameters must be included in the DOCZ Header SINGLE parameters may occur only once per module in the DOCZ Header MULTIPLE parameters may occur as many times as required in the DOCZ Header (except for some limits as described in "Formatting Source"). PARAMETER: .MODULE DESCRIPTION: Module name ARGUMENTS: One REQUIREMENTS: REQUIRED, SINGLE TYPICAL ARGUMENTS: NOTES: Module name and respective arguments must appear on the same line. 31 characters maximum length, case is ignored PARAMETER: .LIBRARY DESCRIPTION: Library name ARGUMENTS: One REQUIREMENTS: REQUIRED, SINGLE TYPICAL ARGUMENTS: NOTES: Delimiters and respective arguments must appear on the same line. 11 characters maximum length. Case is ignored. PARAMETER: .TYPE DESCRIPTION: Type of module ARGUMENTS: One REQUIREMENTS: REQUIRED, SINGLE TYPICAL ARGUMENTS: FUNCTION, PROGRAM, MACRO NOTES: Case is ignored. PARAMETER: .DESCRIPTION DESCRIPTION: Quick summary description ARGUMENTS: Single line REQUIREMENTS: REQUIRED, SINGLE TYPICAL ARGUMENTS: NOTES: Approximately 75 characters maximum length, One line only. It is used in the Quick Description Summary produced by the DOC program. 29 FORMATTING SOURCE CODE PARAMETER: .ARGUMENTS DESCRIPTION: Calling parameters ARGUMENTS: Multi-line REQUIREMENTS: REQUIRED, SINGLE TYPICAL ARGUMENTS: NOTES: Calling parameters for functions and macros. Usually just a copy of the function call. Describe the arguments as to data type. It is used in the Quick Reference Summary produced by the DOC program. PARAMETER: .NARRATIVE DESCRIPTION: Long description ARGUMENTS: Multi-line REQUIREMENTS: REQUIRED, SINGLE TYPICAL ARGUMENTS: Complete narrative NOTES: This area is used to explain the functionality of the module and the uses of the arguments. PARAMETER: .APPLICATION DESCRIPTION: Application keyword ARGUMENTS: One REQUIREMENTS: QUIRED, MULTIPLE RE TYPICAL ARGUMENTS: DATE/TIME, CONVERSION, STRING, SCREEN, SYSTEM NOTES: A word or two to describe the general category of the module. This parameter generates the Application Keyword Summary. Maximum occurrences of this parameter is 8, case is ignored. It is used in the Application Keyword Summary produced by the DOC program. PARAMETER: .SYSTEM DESCRIPTION: Operating system, Version, Compiler ARGUMENTS: One REQUIREMENTS: REQUIRED, MULTIPLE TYPICAL ARGUMENTS: MSDOS, VMS, UNIX System V NOTES: A word or two to describe the supported platform(s). This parameter generates the Platform Summary. Maximum occurrences of this parameter is 8, case is ignored. It is used in the Platform Summary produced by the DOC program. PARAMETER: .AUTHOR DESCRIPTION: Author's name and department ARGUMENTS: Multi-line REQUIREMENTS: OPTIONAL, SINGLE TYPICAL ARGUMENTS: NOTES: 30 FORMATTING SOURCE CODE PARAMETER: .REVISION DESCRIPTION: Revision history ARGUMENTS: One argument (first line) & multi-line REQUIREMENTS: OPTIONAL, MULTIPLE TYPICAL ARGUMENTS: DATE (on the first line) NOTES: The DATE must appear on the same line as the .REVISION delimiter. Comments and notes on the revisions appear on following lines. Maximum number of occurrences of this parameter is 128. It is used by the Revision Notice produced by the DOC program. PARAMETER: .FIXES DESCRIPTION: Fix history ARGUMENTS: One argument (first line) & multi-line REQUIREMENTS: OPTIONAL, MULTIPLE TYPICAL ARGUMENTS: DATE (on the first line) NOTES: The DATE must appear on the same line as the .FIXES delimiter. Comments and notes on the fix appear on following lines. Maximum number of occurrences of this parameter (for one module) is 128. It is used by the Fix Notice produced by the DOC program. PARAMETER: .CAUTION DESCRIPTION: Cautions concerning usage ARGUMENTS: Multi-line REQUIREMENTS: OPTIONAL, SINGLE TYPICAL ARGUMENTS: NOTES: Possible unpleasant side affects, privileges required (VMS), etc. PARAMETER: .OVERHEAD DESCRIPTION: Memory/file usage ARGUMENTS: Multi-line REQUIREMENTS: OPTIONAL, SINGLE TYPICAL ARGUMENTS: NOTES: Code, data, and stack usage PARAMETER: .COMMENTS DESCRIPTION: Miscellaneous notes ARGUMENTS: Multi-line REQUIREMENTS: OPTIONAL, SINGLE TYPICAL ARGUMENTS: NOTES: This is the area to explain caveats 31 FORMATTING SOURCE CODE PARAMETER: .RETURNS DESCRIPTION: Return value and description ARGUMENTS: Multi-line REQUIREMENTS: REQUIRED, SINGLE TYPICAL ARGUMENTS: NOTES: Describe return data type, or if no data returned PARAMETER: .LANGUAGE DESCRIPTION: Source language of module ARGUMENTS: Multi-line REQUIREMENTS: OPTIONAL, SINGLE TYPICAL ARGUMENTS: NOTES: PARAMETER: .EXAMPLE DESCRIPTION: Source code for example ARGUMENTS: Multi-line REQUIREMENTS: OPTIONAL, SINGLE TYPICAL ARGUMENTS: NOTES: PARAMETER: .SEE_ALSO DESCRIPTION: Cross references ARGUMENTS: Multi-line REQUIREMENTS: OPTIONAL, SINGLE TYPICAL ARGUMENTS: NOTES: Names of related functions or programs PARAMETER: .NOTICE DESCRIPTION: Notices ARGUMENTS: Multi-line REQUIREMENTS: OPTIONAL, SINGLE TYPICAL ARGUMENTS: NOTES: Notices, such as copyright declarations PARAMETER: .LSE DESCRIPTION: LSE function call prototype ARGUMENTS: Multi-line REQUIREMENTS: OPTIONAL, SINGLE TYPICAL ARGUMENTS: NOTES: This field is provided for those who wish to write a utility to extract information for their language- sensitive-editors PARAMETER: .REFERENCES DESCRIPTION: External references ARGUMENTS: Multi-line REQUIREMENTS: OPTIONAL, SINGLE TYPICAL ARGUMENTS: NOTES: Names of modules that will be linked from other libraries 32 FORMATTING SOURCE CODE PARAMETER: .CONVENTIONS DESCRIPTION: Conventions utilized ARGUMENTS: Multi-line REQUIREMENTS: OPTIONAL, SINGLE TYPICAL ARGUMENTS: NOTES: Registers saved, registers destroyed, etc, if not obvious PARAMETER: .DIAGRAM DESCRIPTION: Program flow diagram ARGUMENTS: Multi-line REQUIREMENTS: OPTIONAL, SINGLE TYPICAL ARGUMENTS: NOTES: Flow diagram in the caller's favorite code methodology, such as pseudo-code. PARAMETER: .PAGE DESCRIPTION: Page break ARGUMENTS: None REQUIREMENTS: OPTIONAL, MULTIPLE TYPICAL ARGUMENTS: (none) NOTES: .PAGE is actually a pseudo-parameter. Appearance of this parameter at the beginning of a line in the body of the description of a parameter, causes a page-break in the output documentation. PARAMETER: .INCLUDES DESCRIPTION: Required include files ARGUMENTS: Multi-line REQUIREMENTS: OPTIONAL, SINGLE TYPICAL ARGUMENTS: Header file names NOTES: PARAMETER: .ERRORS DESCRIPTION: Action taken on error conditions ARGUMENTS: Multi-line REQUIREMENTS: OPTIONAL, SINGLE TYPICAL ARGUMENTS: NOTES: Descriptions of actions taken as a result of error conditions, such as displaying messages, logging, etc. PARAMETER: .ENDOC DESCRIPTION: End of documentation header ARGUMENTS: No arguments (arguments are ignored) REQUIREMENTS: REQUIRED, SINGLE TYPICAL ARGUMENTS: (NO arguments) NOTES: 33 FORMATTING SOURCE CODE Parameter Summary Parameter Multiple Single Optional Required .MODULE (first) +++++++ +++++++ .LIBRARY +++++++ +++++++ .TYPE +++++++ +++++++ .DESCRIPTION +++++++ +++++++ .ARGUMENTS +++++++ +++++++ .NARRATIVE +++++++ +++++++ .APPLICATION +++++++ +++++++ .SYSTEM +++++++ +++++++ .RETURNS +++++++ +++++++ .ENDOC (last) +++++++ +++++++ .AUTHOR +++++++ +++++++ .REVISIONS +++++++ +++++++ .FIXES +++++++ +++++++ .CAUTION +++++++ +++++++ .OVERHEAD +++++++ +++++++ .COMMENTS +++++++ +++++++ .LANGUAGE +++++++ +++++++ .EXAMPLE +++++++ +++++++ .SEE_ALSO +++++++ +++++++ .NOTICE +++++++ +++++++ .LSE +++++++ +++++++ .REFERENCES +++++++ +++++++ .CONVENTIONS +++++++ +++++++ .DIAGRAM +++++++ +++++++ 34 FORMATTING SOURCE CODE .PAGE +++++++ +++++++ .INCLUDES +++++++ +++++++ .ERRORS +++++++ +++++++ 35 ADDING/UPDATING Building Documentation Libraries To either add or update a module in DOCZ you must: (1) Provide the source file with a documentation header with all required fields filled-in, and as many optional fields filled-in as desirable. One documentation header is required for each of the modules in the source file. (2) Copy or rename the source file containing the module(s) to the location that will be specified as the "source file" to the DOCXL program, or use your version control software to insert the file into the source code library or source code library directory. VMS version: You may wish to convert the file to Stream_LF at this time, so that the DOC program will not have to perform the conversion while it is processing. An FDL is provided in the data directory for this purpose. If the source is to be maintained in a library, instead of copying the file to the CMS documentation directory, use CMS to insert (or update) the file in the CMS library. CONVERT/FDL=DOCDAT:STREAM <filename> (3) Run the DOCXL program to update the Documentation Index File. The command line format for the DOCXL program, to update or add a module is: DOCXL <library name> <module name> <source file> 37 ADDING/UPDATING where: library name is the name you have chosen to collect this program/function logically (see "Naming Conventions"). The library name must not contain any punctuation (except the underscore character). module name is the name for this module. The module name must not contain any punctuation (except the underscore character). source file is the name of the source file containing the module. If the file is to be located in a sub- directory of the default source directory (i.e. pointed to by the DOCSRC symbol or logical name), no device or directory need be specified. The sub-directory name will be the name of the library (in upper case). It is usually most convenient to specify the file name only, but if you choose to specify a full path, the DOCZ system will optionally perform symbol substitution imbedded in directory specifications. Surround the symbol with the dollar sign, ($), and an attempt will be made to find a substitution in the environment (either CLI symbols or (VMS) logical names) when the source file is extracted. For example: $HEADER$fred.c in which an attempt will be made to substitute for HEADER, if an equivalent exists in the environment. The DOCXL program will read the command line arguments and update the Documentation Index with the module's name and file in which it is contained. If the module did not previously exist in the index, it is added at the end, and the introduction date for that module is set to the current date. If the module did previously exist, the modification date and time are set to the current date and time. If a new source file specification for a previously existing module is specified, the file specification field is updated with the new data. The DOCXL program does not open the module source file or attempt to validate the documentation header for the module; this is only done by the DOC program, at the time documentation is being produced. Wildcards are not honored, 38 ADDING/UPDATING and only one module can be added or updated by the DOCXL program at a time (but see the DOCLIS program for automatic multiple adds/updates). If a source file contains several modules, DOCXL must be run once for each module, even though the same source file is specified each time. Modules with the same module name may be specified in different libraries without conflict. It is recommended that lower case be used for file specifications on VMS and MSDOS systems, to allow easier transporting of the Documentation Index File to Unix systems (using the ASCII Transport File feature). The DOC program may now be run against the module. The DOC program will produce the output documentation for one or more modules in a library, or for all modules in a library. The DOC program is also capable of producing Change Notices, Revision Notices, Introduction Notices, and Fix Notices. See the next section for details. 39 PUBLISHING DOCUMENTATION Full Library Documentation The command line format for the DOC program, to produce all of the documentation for a single library is: DOC <library name> For the specified library name, the DOC program will: (1) build a title page as a cover for the documentation (2) format a "library introduction" for presentation at the front of the library documentation. See the next section for details. (3) scan the index for all modules in the specified library (4) sort the module names alphabetically (5) scan each of the source files for the documentation header for each of the modules (6) extract the documentation parameters with their associated arguments (7) reformat the documentation into print image (8) format the print image with page numbers, page headers, page footers, etc. (9) build an alphabetical table of contents (10) build a module description summary (12) build a operating system platform summary (13) build a list of modules with their associated application keywords sorted alphabetically (14) build a set of alphabetically sorted permutations of the module descriptions (15) build a quick-reference of module argument parameters and output it to the documentation (16) if any modules have improper documentation, the names of the modules and the errors detected will be output to a file, <library name>.ERR. 41 PUBLISHING DOCUMENTATION Printing The DOC program does not print directly to print devices or queues. It produces a file, <library name>.DOC in the default directory which has been formatted into print image and can be sent to a printing device. The file can be deleted after printing, if it is no longer needed. The Library Introduction When the full library documentation is generated, the DOC program searches the Documentation Reference Directory for a file with the same name as the library specified, and with the extension ".COV" (in upper case on the Unix platform). If found, this file will be reformatted into print image and presented after the title page of the library documentation. This file should contain raw text, with no documentation parameters. For example: the name of the library for which your are generating full library documentation is "CLIB." The DOC program is invoked by: DOC CLIB The Documentation Reference Directory is scanned for a file named "CLIB.COV," and it is included in the output documentation just after the title page. 42 PUBLISHING DOCUMENTATION Revision/Fix Notices The command line format for the DOC program, to produce a Revision Notice for a single library name is: DOC <library name> </r[=DATE]> The command line format for the DOC program, to produce a Fix Notice for a single library name is: DOC <library name> </f[=DATE]> If the options are specified with no dates, as in: DOC ULIB /F the current day's date will be used (see the DOCZ PROGRAM REFERENCE, EXAMPLES). Revision and Fix Notices are based on the dates in the documentation headers accompanied by the respective .REVISION or .FIXES parameters. The revision or fix description and date are provided by the programmer when the changes to the code is performed. The revision or fix date is specified in the usual date (leading zeros not required in the default date format format), and the date is inclusive. Case is ignored in all arguments to DOC. For the specified library name, the DOC program will: (1) build a title page as a cover for the documentation that specifies that this documentation is a revision or fix notice (2) scan the index for all modules in the specified library that have a modification date equal to or later than the date specified on the command line (3) sort the module names alphabetically (4) scan each of the source files for the documentation header for each of the modules (7) extract the documentation parameters with their associated arguments for only those modules that have a revision or fix date specified (with the .REVISION or .FIXES parameter) that is the same as, or later than the date specified on the command line to the DOC program. All source files will be read, but documentation will be output for only those modules that match the above criteria. (8) reformat the data into print image, as for the full library documentation. 43 PUBLISHING DOCUMENTATION (9) no index, quick-reference, table of contents, or application keyword index will be output. 44 PUBLISHING DOCUMENTATION Change Notices The command line format for the DOC program, to produce a Change Notice for a single library name is: DOC <library name> </m[=DATE]> (1) Operation is the same as a Revision/Fix Notice, except that only modules that have been modified on or since the date specified will have documentation output. The documentation headers do not have to be modified for Change Notices. Modification dates are maintained in the Documentation Index File. This Change Notice is provided to provide library documentation to users who must be provided with the very latest documentation. Library Summary A Library Summary consists of the following: (1) a title page as a cover for the documentation (2) a "Library Introduction" for presentation at the front of the library documentation. (3) a module description summary (4) an operating system platform summary (5) a list of modules with their associated application keywords sorted alphabetically (6) a set of alphabetically sorted permutations of the module descriptions (7) a quick-reference of module argument parameters and output it to the documentation (8) if any modules have improper documentation, the names of the modules and the errors detected will be output to a file, <library name>.ERR. 45 PUBLISHING DOCUMENTATION All of this information is provided with the "Full Library Documentation" except that none of the individual module documentation appears in the Library Summary. You will find that the publishing of several introduction, revision, and/or fix notices may make the summary substantially out- of-date (some programmers may tend to use only the summary, anyway). The /s option provides a current summary. DOC <library name> </s> 46 PUBLISHING DOCUMENTATION Single Module Documentation The command line format for the DOC program, to produce documentation for one or more modules in a library is: DOC <library name> <module name> or DOC <library name> <module name> <module name> ... (1) Only the documentation for the module or modules specified, will be generated. There will be no title page, index, quick-reference, or application keyword index. Whenever a new module is added to your DOCZ library, you should run the DOC program on the module to verify that the documentation header has been formatted correctly. 47 SELECTING OPTIONS The Configuration File A great variety of options are enabled and customized through the use of the Configuration File. This section explains how to format records in that file to select such options as printing output enhancement, error and informational logging, alternate directory structures, language independence, and custom interfaces to version software. control The Configuration File is a text data file and can be generated with a text editor. The file name must be "DOCZ.CFG" (in upper-case on the Unix platform). A prototype DOCZ.CFG file is produced during the installation procedure. There can be more than one DOCZ Configuration File on the system at a time. This condition is allowed to support Configuration Files for several different printers on the system. The DOCZ programs search the current directory first for the Configuration File. If none is found in the current directory, the Documentation Reference Directory is then searched. The Printer Interface DOCZ provides a means to enhance the format of the output documentation through the use of printer features. Due to the immense number of features available on today's printers, only a minimum number of features can be implemented; but, they are the type of features that provide for very readable documentation. You will find that a large library under the control of a DOCZ System can produce very voluminous documentation. Hence, you will want to get as many lines of output on your printed documentation as is possible, while still maintaining readability. If the Configuration File does not exist or does not contain any printer options when the DOC program is run, the output will be formatted for a "generic" printer. A minimum requirement for any printer used by DOCZ is that the printer be able to perform a form-feed. 49 SELECTING OPTIONS To select printer options, Configuration File records are formatted as in: KEY,PARAMETER where: KEY PARAMETER PC, Number of columns (Ex: 132, default is 80) PN, Number of lines per page (default is 66) PL, Left margin (default is 0) PR, Right margin (default is 0) PA, Name of the printer (default is no printer name) PI, Initialization tokens from PSET (up to 8) PE, Exit tokens from PSET (up to 8) The KEY case is ignored, and the case of the PSET tokens is always ignored. All occurrences of KEYs in the Configuration File are optional, and only the parameters specified will be modified. If not modified, all parameters will default to values appropriate for a "generic" printer. See the DOCZ Utility documentation for more information on installing printer control sequences using PSET and/or PCODE. The KEYs must be the first character in the line. If a pound symbol (#) appears as the first character in a line, that line is ignored (and taken as a comment). The printer name, specified by 'pa', must be the same as the installed in the PSET database for the _PRINTER token VMS version: PSET.DAT must be in the data directory. DOCZ.CFG must be in the current directory or the Reference Directory MSDOS & UNIX: PSET.DAT must be in the search PATH. DOCZ.CFG must be in the current directory or the Reference Directory An example of DOCZ.CFG: # the name of the printer pa,DEC LN03 # 88 columns pc,88 # 60 lines pn,60 # left margin = 8 pl,8 # initialize, reset to power-up state pi,lzreset # vertical pitch = 9 50 SELECTING OPTIONS pi,lzvp8 # horizontal pitch = 12 pi,lzhp12 # defeat top and bottom margins pi,lznotbm # exit, reset to power-up state pe,lzreset The pa parameter in the above example causes the DOC program to verify the PSET database for the printer specified. If the argument matches the printer installed in the PSET database with the PCODE utility, character attributes will be utilized to enhance the appearance of the output documentation. To defeat the use of character attributes, omit the use of an pa parameter. The pc parameter specifies that 88 columns will be produced in the output; this assumes that the horizontal pitch on the printer will have been adjusted to allow 88 columns on the printed page. The pn parameter specifies that only 60 lines per page will be output, instead of the default 66. 51 SELECTING OPTIONS The four pi parameters specify four tokens that will be matched from the PSET database to provide four initialization sequences to be output to the printer before any printing is done. The single pe parameter specifies an exit sequence that will be sent to the printer at the end of printing. Note that the tokens specified in the above example are user-supplied (provided by you). In a typical application, the above example tokens could represent: lzreset = reset to power-up configuration lzvp8 = set vertical pitch to 8 l.p.i. lzhp12 = set horizontal pitch to 12 c.p.i. lznotbm = defeat top and bottom margins The DOCZ Installation Kit will provide a prototype DOCZ.CFG Configuration File, but it will contain no print formatting information. No assumptions about your printer hardware are made. The PCODE utility is supplied with DOCZ to provide printer features for many of the popular brands of printers. You may add your own parameters to the prototype DOCZ.CFG. 52 SELECTING OPTIONS Multiple Language Support The compiler or assembler is made to ignore everything in the documentation header by surrounding the documentation header with conditional compile (or assembly) directives (for those languages that support such). Most PASCAL and C compilers and many Assembly language assemblers allow conditionals. For languages that allow only single-line comments, such as BASIC, COBOL, and FORTRAN, the user may specify a "comment string mask" that describes the comment format for the language being used. The comment string mask may be specified to the DOCZ system using the DOCZ Configuration File (DOCZ.CFG) by specifying the file name extension associated with files containing the computer language (see "Specifying Comment String Masks for File Extensions" in a following section). Specifying a Comment String Mask The comment string mask is formatted such that: ? hes any single character matc n causes all numerics to be skipped (such as line numbers). n is specified only once in the comment string mask to skip all numerics starting at the corresponding position in the input source line. Any other character is matched literally (including spaces and TAB characters). The comment string mask is always specified with double quotation marks to preserve leading or trailing blanks. DOCZ System programs always expand TAB characters to spaces at tabstop eight, or to the tabstop specified with the o option in the Configuration File. Consequently, if a TAB is part of the comment string mask, it must be replaced with the requisite number of spaces. Comment String Mask Examples: BASIC "n '" Match any number of digits that start in column one, then match a space, then match an apostrophe. COBOL "* " Match an asterisk in column one and a space in column two. 53 SELECTING OPTIONS FORTRAN "C " Match an upper-case C in column one and space in column two. Note that if a TAB were to follow the 'C' in the FORTRAN example, the comment string mask would be specified: "C " which is a 'C' followed by seven space characters. This mask will match when the DOCZ programs expand TAB characters to spaces at tabstop eight. Specifying Comment String Masks for File Extensions This method for specifying a comment string mask using DOCZ.CFG applies a comment string for every source file with a specified file name extension. The entries in DOCZ.CFG are specified as in: E,<extension>,<comment string mask> The following is also valid: E,,<comment string mask> and specifies a comment string mask for filenames with no extension (such as Unix shell scripts). The following comment string masks are provided in the prototype Configuration File by the Installation Program and may be added-to or modified to suite your development environment: E,BAS,"n '" E,COB,"* " E,FOR,"C " E,PRG,"* " The case of parameters is always ignored. For assemblers that do not allow "ifdefs," you may need to add: E,ASM,";" 54 SELECTING OPTIONS Transaction Logging The DOCZ programs provide a logging facility that can help automate the administration of a DOCZ System. The logging facility allows the recording of errors and information in a file in the Documentation Reference Directory, named DOCZ.LOG. The various levels of logging are: Informational (I) Status or result of an operation Warning (W) Notification of an unnatural condition, but that does not prevent DOCZ processing Error (E) Notification of an incorrect condition that probably prevents normal processing Fatal (F) A severe error condition that may leave DOCZ files in an unknown state or condition that may have to be manually repaired. Statistics (S) Information about time and resources for statistical purposes. All such conditions are always echoed to the controlling terminal, but, in an automated DOCZ System, such message are often lost or left unnoticed. If logging is enabled, these messages will be stored where they can be retrieved for examination at a later time. The error level (i.e. Informational, Warning, Error, Fatal, or Statistical) that is logged is under user control: that is the user can specify zero or more error levels to be logged. The logging error levels are specified in the Configuration File using an entry in the following format: L,<error level list>,<number of days to keep entries> where the error level list (field number 2) may contain zero or more of I, W, E, or F. The default is E and F, which will be used if there is no 'L' record in the Configuration File. This means that, by default, there will be a DOCZ.LOG created in the Documentation Reference Directory and it will contain messages for every Error and Fatal condition. The number of days to keep entries (field number 3) specifies the number of days to age entries before they expire and are removed from the log (to prevent the log from growing endlessly). The default aging period is thirty days. 55 SELECTING OPTIONS An empty field number two, as in: L, defeats all logging. The following example: # log all messages L,IEWFS,60 specifies that all error levels are to be logged, and entries over sixty days old will be removed (the '#' character precedes comments in the Configuration File). As in the other DOCZ programs and utilities, case is always ignored. Aged entries are always checked the first time a DOCZ program accesses the log, consequently, if a log "cleaning" operation is required (aged entries to be removed), there will be a slight delay in the program while the "cleaning" operation is carried out. This negates the need for an administrator to manually force a periodic clean-up of the DOCZ log. If "informational" (I) logging is enabled, a history of the DOCZ System usage will be maintained in the log. This can be a substantial help when administering a DOCZ System that exists on more than one operating system platform. The DOCLOG program is provided to scan the DOCZ log and produce reports from it (see the documentation for DOCLOG). DOCZ programs that log DOCZ programs that do not log DOC DOCHELP DOCXL DOCLOG DOCXLU DOCGET DOCHBLD DOCLIS DOCXLED DOCMAN DOCLEARN 56 SELECTING OPTIONS Alternate Directories and Version Control The Configuration File provides a means for bypassing the DOCZ paths naming conventions to make it easier to apply the DOCZ System to an already existing development environment. In addition, the means is provided to call almost any version control software, should the user not use CMS for VMS or SCCS for Unix System V. Either or both of these options are selected using the U parameter in the Configuration File such that: U,[library name],[path],[get command],[DEL] where library name may be an empty field or a library name. If the library name is empty then ALL libraries will be specified with the U option. If not empty, only the named library will be specified with this U option. Note that multiple U records may be specified (up to one per library). path may be an empty field or a path to the source files, containing the token, "$FILE$," for which the source file name will be substituted at run time. If path is an empty string the default DOCZ path will be used (using the DOCSRC symbol/logical name). If not empty, DOCZ will substitute the source file name for $FILE$ in the string specified in this field of the U record, to form a path to the file. get command may be an empty field or a command to execute for each module being documented. If get command is an empty field, the source file will be used with the path specification. If not empty, the get command will be executed with the following substitutions being performed for each module: $FILE$ source file name $LIB$ current library name $MOD$ current module name $DOCSRC$ the DOCSRC directory $DOCREF$ the DOCREF directory The get command may be either a command file or program and must be specified appropriately for the native command interpreter to execute it. The net result of the get command must be to deliver the file 57 SELECTING OPTIONS into the current (default) directory, with the name specified as in the Documentation Index File. This is the same action as a 'get' using SCCS, a 'co' (check-out) using RCS, or a 'fetch' using CMS. This command should not place a reservation on the file. DEL if present as the fifth field of a U record, means that the file should be deleted from the current directory when DOCZ is done with it. If the get command is a version control "extraction," this option allows the removal of the file when DOCZ processing is complete, but this option is only valid in conjunction with a get command (fourth field). Fields may be quoted with either the double quote character or the apostrophe if they require embedded commas, apostrophes, or double-quotes. For (an MSDOS) example: U,USRLIB,\source\rcs\$FILE$,co \source\rcs\$FILE$,del where: the source file can be located by substituting the source file name as stored in the Documentation Index File for the $FILE$ token in "\common\source\rcs\$FILE$", and can be "gotten" or "fetched" into the default directory by executing the command line, "co \common\source\rcs\$FILE$". When the DOCZ program is done with the file, it will delete it, as specified by del in the fifth field. Another (Unix) example: U,,"/u/$LIB$/$FILE$,v",'co /u/$LIB$/$FILE$,v ""',del Since field number two is empty, all libraries will use this U record as a rule. Note that both field three and four are quoted to preserve the comma that must be embedded in the file specification; field four is quoted with the apostrophe to preserve the double-quote that must be embedded in the field. Some will recognize the get command in the previous two examples as a Berkeley Unix RCS "check out" command. Another (VMS) example: U,CLIB,DUA0:[USER.COMMON.SOURCE]$FILE$,, Case is always ignored in the substitution parameters (i.e. $FILE$ and $file$ are equivalent), and in the U record identifier, the U character. 58 SELECTING OPTIONS MSDOS Username MSDOS does not have the capability to identify the owner of a process, but the DOCZ log contains the username in each entry. Therefore, the DOCZ system has the option of providing a username in the DOCZ log if the environment variable, LOGNAME, is defined. For example: SET LOGNAME=todd will log the name "todd" as the username. This may be especially useful on a PC network that uses a shared DOCZ log. Variable TAB Expansion TAB expansion to suite your tastes may be specified via the Configuration File using an o record, as in: o,tabs,<tabstop> This will cause TABS to be expanded to tabstop, instead of eight (the default). For example: o,tabs,3 while force TABS to be expanded to three spaces. You will need this option in your configuration file to match TAB expansion that may be performed by your program editors. The DOCZ System performs TAB expansion when producing documentation via the DOC program, and during generation of on-line help libraries via the DOCHBLD program. 59 SELECTING OPTIONS Specifying Command Line Options The [z_opt] command line option that is common to many of the DOCZ programs allows the overriding of DOCZ symbols and default directory specifications. The [z_opt] option can be specified once or twice on the command line such that: /z=docref=<alternate DOCREF directory> selects a new DOCREF directory, or if specified as an empty string as in: /z=docref= Specifies that the DOCREF directory is the current directory. Identical behavior is valid for: /z=docsrc=<alternate DOCSRC directory> Case is ignored in the identifiers 60 SELECTING OPTIONS Option Summary Options selected via the Configuration File. Transaction Logging L,<error level list>,<number of days to keep entries> Printer Interface P<feature key>,<value> Comment String Mask E,<extension>,<comment string mask> Alternate Directories/Version Control U,[library name],[directory],[get command],[DEL] Variable TABs O,TABS,<tabstop> Symbol Override /z=docref=<alternate DOCREF directory> /z=docsrc=<alternate DOCSRC directory> 61 DOCUMENTATION INDEX Dumping the Documentation Index Should the need arise to examine the Documentation Index to determine what, and how many modules it contains; DOCXL with the following command line may be used: DOCXL /d The entire contents of the Documentation Index will be dumped (in displayable format) to the current output device. For each module, the following is displayed: Library name Module name Date of last modification (in the Documentation Index) Time of last modification Date of introduction If the contents of only one library is required, DOCXL also accepts a library name as its first argument, such that DOCXL [library name] /d Only the modules for library name will be dumped. Displaying Modules Modified Since a Date DOCXL /dm[=DATE] DOCXL [library name] /dm[=DATE] All modules in the index that have been modified on or since the date specified, will be displayed, regardless of which library they are in. If no date is specified, the current date is assumed. Displaying Modules Introduced Since a Date DOCXL /di[=DATE] DOCXL [library name] /di[=DATE] All modules in the index that have been introduced on or since the date specified, will be displayed, regardless of which library they are in. If no date is specified, the current date is assumed. 63 DOCUMENTATION INDEX Deleting a Module DOCXL <library name> <module name> /x The specified module name in the specified library name will be deleted from the Documentation Index. The actual file that contains the module will not be affected, only the Documentation Index entry for the module. The deletion must be interactively confirmed by the user. Searching for a Module DOCXL <module name> /s[=<output file>] The index will be searched for the module name specified, and all matching names in all libraries will be displayed. If an optional output file is specified, it will be appended with the results of the search. Wildcards are not allowed in module names. Feeding the Documentation Index to Other Programs DOCXL <library name> /o[=L[M[F[D[T]]]]] The Documentation Index may be output as a text data file in a variety of formats that may be used as in input to other user-written programs using the DOCXL /o option. The /o option specifies that all modules in a specified library are to be matched and the fields in the Documentation Index are to be output. The output will be contained in a file named, library name.LST, in the current directory. The /o option may be followed by an equals character and one or more additional specifiers in any order: L list library name M list module name F list file name D list date of update T list time of update Any combination of specifiers may be specified, and the output will contain the specified fields in the order you specified. If no arguments are specified with /o, then all fields will be output in the default order. The output file, library_name.LST, is in the text data format. You may wish to sort the file using your operating system SORT utility. 64 DOCUMENTATION INDEX Reorganizing Documentation Index Files In very large DOCZ installations it may become advantageous to provide more than one Documentation Index File. For instance, you may have a requirement to maintain an experimental set of documentation in addition to a production set. DOCXL can be used to create a second (or additional) Documentation Index File using the /e option. This option will extract all modules associated with the named library and place them in another Documentation Index File. If the other index file already exists, it will add them to the file. DOCXL <library name> <other Reference Directory> /e Only the directory specification is provided as the second argument, as the file name, DOCXL.DAT, is assumed. Be sure to modify the required logical names or CLI symbols before running the DOC programs on the other index file. See the "DOCZ PROGRAM REFERENCE" section for more information on using the DOCXL program. 65 DOCZ PROGRAM REFERENCE DOC Documentation generation program Arguments DOC <library name> [z_opt] Document an entire library DOC <library name> <module name> [module name] ... [z_opt] Document a single module DOC <library name> </m[=DATE]> [/s] [z_opt] Document modules modified since DATE DOC <library name> </r[=DATE]> [/s] [z_opt] Document modules revised since DATE DOC <library name> </f[=DATE]> [/s] [z_opt] Document modules fixed since DATE DOC <library name> </i[=DATE]> [/s] [z_opt] Document modules introduced since DATE DOC <library name> </s> [z_opt] Produce a library summary Returns EXITNORMAL If one or more modules match command line criteria. EXITWARN If no modules match command line criteria. EXITBAD If DOC cannot run. 67 DOCZ PROGRAM REFERENCE Errors (1) to library_name.ERR in the current directory to the log, if logging is enabled (2) (3) to Standard Error Output to library_name.DOC in the current directory For an explanation of the [z_opt] command-line option, see "SELECTING OPTIONS: Specifying Command Line Options." The /s on the command line with the fix, introduction, revision, and/or modification notice options produces a summary of the modules in the notice with output going to a file with the name: <library_name>.MOD modification notice <library_name>.REV revision notice <library_name>.FIX fix notice <library_name>.INT introduction notice DOC Examples DOC clib Produce the entire documentation set for the CLIB library. DOC clib strfunc Produce the documentation for the module, STRFUNC, contained in the library, CLIB. DOC clib /i=8/10/82 Produce the documentation for all modules in the CLIB library that have been introduced since 8/10/82. DOC clib /f Produce the documentation for all modules in the CLIB library that were "fixed" today. 68 DOCZ PROGRAM REFERENCE DOCXL Documentation Index File update Arguments DOCXL <library name> <module name> <source file> [z_opt] Add/update a module DOCXL [library name] /d [z_opt] Display the Documentation Index DOCXL [library name] /dm[=DATE] [z_opt] Display modules modified since DATE DOCXL [library name] /di[=DATE] [z_opt] Display modules introduced since DATE DOCXL [library name] /p [z_opt] Print (output) the Documentation Index DOCXL [library name] /pm[=DATE] [z_opt] Print (output) modules modified since DATE DOCXL [library name] /pi[=DATE] [z_opt] Print (output) modules introduced since DATE DOCXL <library name> <module name> /x [z_opt] Delete a module (with confirmation) DOCXL <library name> <module name> /xx [z_opt] Delete a module (without confirmation) DOCXL <module name> /s [z_opt] Search for a module DOCXL <library name> /o[=L[M[F[D[T]]]]] [z_opt] Output Documentation Index fields 69 DOCZ PROGRAM REFERENCE Returns EXITNORMAL If the Documentation Index File can be opened. EXITBAD If DOCXL cannot run. Errors to the log, if logging is enabled (1) to Standard Error (2) The DOCXL program is used to build the Documentation Index File for all modules to be documented in the DOCZ System. The /d and /p options respectively allow displaying and printing of the Index for one or all libraries. The DOCXL program does not use any files containing documentation headers: it only manipulates the Documentation Index File. Whenever records in the Documentation Index File must be locked for an inordinate length of time (a few seconds), a message will be displayed on the user's terminal warning of the delay (VMS version only). More information on the usage of the DOCXL program is contained in the section,"DOCUMENTATION INDEX." For an explanation of the [z_opt] command-line option, see "SELECTING OPTIONS: Specifying Command Line Options." 70 DOCZ PROGRAM REFERENCE DOCXL Examples DOCXL clib strfunc strfunc.asm Add the STRFUNC module, contained in the STRFUNC.ASM file, to the CLIB library. DOCXL /p Output a printable image of the contents of the Documentation Index to the file, DOCXL.LST. DOCXL clib /o=ml Output module names and library name (in that order) to CLIB.LST. DOCXL paslib /o Output all module information to PASLIB.LST. DOCXL forlib /dm Display all modules modified today. DOCXL ulib /pi=8/2/86 Output all modules introduced since 8/2/86 to ULIB.LST. 71 DOCZ PROGRAM REFERENCE DOCXLU Documentation Index File utility Arguments DOCXLU /e <Ref. Directory> <library>...[library] [z_opt] Extract library for another Documentation Index File DOCXLU /r [z_opt] Repair/rebuild the Documentation Index DOCXLU /ao=<output file> [library]...[library] [z_opt] Output an ASCII transport file for the Documentation Index DOCXLU /ai=<input file> [z_opt] Read an ASCII transport file DOCXLU /s[=<output file>] [z_opt] Display DOCZ System statistics DOCXLU /v[=<output file>] [z_opt] Verify presence of all source files DOCXLU /c[=<output file>] [z_opt] Check for the presence of rogue files Returns EXITNORMAL If the Documentation Index File can be opened. EXITBAD If DOCXLU cannot run. Errors (1) to the log, if logging is enabled (2) to Standard Error 72 DOCZ PROGRAM REFERENCE The DOCXLU program provides a variety of utility functions that allow moving your DOCZ system between the various operating systems on which it runs. It also helps to reorganize your documentation libraries by providing a means to create several Documentation Index Files. The /e (extract) option is provided to allow the extraction of modules associated with one library to be inserted into another Documentation Index File. The reference directory specifies the directory name containing the Documentation Index File to receive the new entries. The library argument specifies one or more libraries to "extract." The /r (repair/rebuild) option checks the integrity of each field in the Index and extracts records marked for deletion. The /ao (output) option will produce an ASCII transport file, specified by output file, that can be read using the /ai (input) option on another system. This has the affect of duplicating identical DOCZ libraries on more than one system, and those systems need not have the same hardware architecture. For the /ao option, If no library names are specified, all entries will be output. If any library names are specified, then only entries for those libraries will be output. The /ai option is provided to read an ASCII transport file created by the /ao option of DOCXLU. The entries gleaned from the transport file will be merged with the current Documentation Index File. If an entry is new, it will be added. If the entry already exists (module and library name are the same), it will replace the already existing entry. File specifications generated under one operating system may not be valid under another operating system. If the source file name contains a directory specification, you may have to edit it in the ASCII transport file. The UNIX version of DOCXLU will warn of this condition. The /v option initiates a check for the presence of source files for all modules named in the Documentation Index. An optional output file may also be specified, if a print file is required instead of a display. Note that this option does not cause the source files to be validated for properly formatted documentation headers. The /c option checks the default source location for the presence of rogue files (those that cannot be accounted for in the Documentation Index File). The directory searched is the derivation of DOCSRC and the library name (the standard DOCZ default). 73 DOCZ PROGRAM REFERENCE The /s option generates a display of DOCZ System statistics. This option is especially useful for analyzing the entire DOCZ System environment which can be especially useful when error conditions occur. The /s option may be followed by an optional output file specification into which the statistics will be written instead of displayed. The following statistics are displayed: S /no if the VMS version of DOCZ links to CMS Yes S Total number of entries in the Documentation Index File S Number of deleted entries in the Documentation Index File S The directory path to the Default Source Directory S The directory path to the Documentation Reference Directory S Yes/no if a Configuration File can be found S Comment String Masks (if specified in the Configuration File) S Comment String Masks for file extension names (if specified in the Configuration File) S Yes/no if error logging is enabled S Error logging levels that are enabled S The number of days error log entries are kept S The age of the oldest entry in the error log S The total number of entries in the error log S Any print output modification parameters (PSET tokens) S Any PSET initialization and de-initialization parameters specified S The system date format S Yes/no if an on-line help library has been generated and is available S The number of modules in the on-line help library S Yes/no if MSDOS network sharing is enabled (MSDOS version only) 74 DOCZ PROGRAM REFERENCE S Yes/no if the SORT utility is found on the system (it is needed by the DOC program). VMS and UNIX require the system sort, and MSDOS requires SSORT provided by the DOCZ System. S The names of all libraries specified in the Documentation Index and the number of modules in each library S Default source location override (if any) in the Configuration File S Version control GET commands (if any) in the Configuration File For an explanation of the [z_opt] command-line option, see "SELECTING OPTIONS: Specifying Command Line Options." 75 DOCZ PROGRAM REFERENCE DOCXLU Examples Suppose a DOCZ library existed on a Unix system, but an administrator wished to provide a duplicate DOCZ system on an MSDOS LAN. The administrator could use the /ao option, as in: docxlu /ao=tomsdos.txt to produce and ASCII transport file on the Unix system named tomsdos.txt. The administrator would then copy the file (in text mode) to the MSDOS network, set up the MSDOS environment for the DOCZ system, and copy all the source files containing modules to the MSDOS network. Then use the /ai option, as in: docxlu /ai=tomsdos.txt to build a Documentation Index File on the MSDOS network. The source files may then be copied to the requisite sub- directories of DOCSRC, if documentation needs to be built on that platform. The DOCXLU /e option strips entries out of the current Documentation Index File and places them in another Documentation Index File. This feature could be used to isolate documentation for different software releases, both existing on the same system: the environment variables would have to be appropriately modified before accessing the desired DOCZ library. 76 DOCZ PROGRAM REFERENCE DOCHBLD Generate a documentation help library Arguments DOCHBLD [library] [library] ... [/opt] [/opt] options: /h update the on-line help library /v VMS help library format /ao=<filename> ASCII transport output /ai=<filename>[,filename,...] ASCII transport input /z=docref=<alternate DOCREF directory> /z=docsrc=<alternate DOCSRC directory> Returns EXITNORMAL If one or more modules are found and added to the help library EXITWARN If zero modules are found, or any other abnormal condition EXITBAD If any fatal errors occur Errors (1) to the log, if logging is enabled (2) to Standard Error DOCHBLD builds an on-line help library for the modules in the Documentation Index File. It also can build a help library from the modules on another computer using "ASCII transport files." If DOCHBLD is invoked with the /h option, a help library will be built for all modules in the Documentation Index File. The output file, DOCHELP.HLP, is stored in the Reference Directory. This file may then be used by the DOCHELP utility to provide on-line documentation and a program editor interface. An alternate format is available in the VMS version (using the /v option) and this file may then be processed by the VMS LIBRARY utility to produce a text library in a format that can be read by the VMS on-line HELP facility (should you choose to use VMS HELP instead of DOCHELP). The output file will be "DOCHELP.VLP" in the current directory. 77 DOCZ PROGRAM REFERENCE The /ao option produces an "ASCII transport file," with the specified filename, that may be moved to another computer and processed by the DOCHBLD utility (using the /ai option) to produce a help library on the other computer. This feature allows the transportation of a help library between disparate computer architectures. The /ao option excludes the use of the /v option. The library argument is optional and, if any libraries are named on the command line, only the named libraries will be included in the help library. The specification of library names are in compatible with the /ai option. If no library names are specified on the command line, DOCHBLD will generate a help library for all libraries. It is good practice to periodically update the DOCZ Help File by running DOCHBLD, perhaps weekly if your libraries change often. The /h (update help library) option may be specified alone, or in conjunction with the /ao option. This option signifies that the local on-line help library should be updated. The /h option is provided so that (with it left off the command-line) Transport Files can be generated for a limited number of libraries. For an explanation of the [z_opt] command-line option, see "SELECTING OPTIONS: Specifying Command Line Options." A VMS command file, such as the following, generates an on- line help library for all modules documented in DOCZ when DOCHBLD is used with the /v option. $! run the DOCHBLD utility $ DOCHBLD /v $! run the LIBRARY utility to generate a VMS help file $ LIBRARY/HELP/CREATE DOCHELP.VLP DOCHELP $! allow the VMS HELP command to find the help library $ DEFINE/SYSTEM HLP$LIBRARY - 'F$ENVIRONMENT("DEFAULT")'DOCHELP Run the VMS HELP utility, and check for the names of the modules contained in the DOCZ System. 78 DOCZ PROGRAM REFERENCE DOCHELP Produce on line documentation help Arguments DOCHELP (interactive mode) or DOCHELP <module name> [/opt] (command line mode) Returns Nothing Errors to Standard Error The DOCHELP utility reads the help file generated by the DOCHBLD utility to provide on-line documentation for modules. In the interactive mode, module names are accepted at the DOCHELP> prompt until [RETURN] alone is pressed. In command line mode, DOCHELP is invoked with the name of a module on the command line. The following information is stored in the help file and displayed by DOCHELP when a valid module name is entered: Module name Library name Application keyword Short description Return value Argument description The module name may contain the '*' wildcard which will be used to match one or more module names in the help library. The '*' is specified as a trailing character in the module name specification. In this display mode, only module names are displayed. For example, if "c*" is entered, all module names beginning with "c" are displayed. If "*" is entered, all module names are displayed. The screen will be "frozen" to prevent it from scrolling, and any key pressed will continue the display. A question mark, '?', in place of a module name displays the DOCHELP banner with a list of usage prompts. A description search capability is available in the interactive mode. One or more keywords may be entered at the DOCHELP> command prompt, preceded by a slash (/) character. 79 DOCZ PROGRAM REFERENCE In the following example: DOCHELP> /lower case will search all module descriptions (without regard for case) and will display those containing the string, "lower case." The module name and library name are also displayed. This feature allows easy location of modules by description. If /arg as added as an option in command line mode, only the arguments for the module are displayed. This option is available primarily to provide a means for producing function prototypes for editors: the "DOCHELP <module name> /arg" output can be redirected to a file and the file and then read by the program editor. There are two mechanisms supplied with the DOCZ System to extract a modules' arguments (or calling prototype) while you are in an editing session: (1) In the UNIX version, DOCHELP can be used to insert a function prototype into the current document under edit by entering, in command mode in the vi editor: :r !dochelp <module name> -arg The function prototype for the module name will be inserted into the text at the current cursor position. (2) In the MSDOS version, if you are using the BRIEF editor, The DOCZ distribution includes the source code for a BRIEF macro. Licensed BRIEF users only need compile the macro, DOCHELP.M, and place the compiled macro in their BRIEF macro directory. The macro is invoked from the BRIEF command mode by entering: dochelp <module name> The function prototype for the module name will be inserted into the text at the current cursor position. 80 DOCZ PROGRAM REFERENCE DOCXLED Examine/search/modify the Documentation Index File Arguments DOCXLED [z_opt] Returns Nothing Errors to the log, if logging is enabled (1) to Standard Error (2) The DOCXLED utility provides the means to examine and modify records in the Documentation Index File. Each of the following fields in each record may be modified using the primitive screen editor in the DOCXLED utility: Library name Module name Source file specification Last modification time Last modification date Introduction date Delete/undelete record 81 DOCZ PROGRAM REFERENCE The following is a display produced by the DOCXLED program: ************************************************** Entry Number: 0 Library name: DOCZ Module name: DOC Location: doc.c Modification date: 12/11/89 Modification time: 22:15:50 Introduction date: 07/07/87 Deleted record? N Records=566, Search direction=FORWARD, Search library=* ************************************************** +) Next, -) Previous, B) Begin, Z) End, S) Set Rec. No. F) Find, Q) Quit, D) Direction, N) Name library, E) Edit, U) Update Press choice: When the DOCXLED program is run, the first entry in the Documentation Index File is displayed, and the user is placed in the command mode. Any entry that is displayed on the screen may be edited by pressing E, which places the user in the editing mode. For an explanation of the [z_opt] command-line option, see "SELECTING OPTIONS: Specifying Command Line Options." 82 DOCZ PROGRAM REFERENCE In the command mode, you may select any of the following options: Q Quit DOCXLED utility + Display next entry - Display previous entry B Display first (beginning) entry in file Z Display last entry in file F Find a module name you will be prompted for. During the search, an abort key (^\) can abort the search. D Change the direction of search N Name a new library. '*' signifies that all library names will be included in the search. E Enter editing mode on the current record U Update an edited record S t the current record number Se While in the editing mode, the following function keys will be recognized: Key Action Control-E Previous field RETURN Next field Control-K Abort Control-Z Exit BACKSPACE, DELETE Delete character Control-U Clear current field A terminal independent primitive editor is utilized in the editing mode to allow modifications to the Documentation Index File records. When the cursor is in a field, the maximum width of the field will be displayed filled with the underscore character. When editing mode is exited to command mode, the entry will be updated in the Documentation Index File if you press U. If you move to another entry without pressing U, your edits will be lost. DOCXLED does not allow new entries, it only allows modification of entries previously added by DOCXL. It does, however, allow the marking of an entry for deletion. A 83 DOCZ PROGRAM REFERENCE record marked for deletion may be overwritten by the next new entry applied to the Documentation Index File, or will be removed entirely by the "rebuild" option of DOCXL. Specifying a library name with the N option causes subsequent searches to scan only for the library name you specify. To return to a global search, select N, and enter *. 84 DOCZ PROGRAM REFERENCE DOCGET Extract a field from a documentation header Arguments DOCGET <module> <source> <parameter> [/o=<output>] Returns Nothing Errors to Standard Error The DOCGET utility extracts a single field for a module from a documentation header specified by the DOCZ header parameter. Only the first 3 characters of parameter will be used, and case is ignored. The module name must be specified as multiple modules may be contained in a single source file. If an optional output file is specified, it will be appended to. This utility is provided to facilitate automation of the DOCZ System. 85 DOCZ PROGRAM REFERENCE DOCLIS Find all DOCZ modules in a source file Arguments DOCLIS <a.f.n.> [/o=<output file>] DOCLIS <a.f.n.> [z_opt] /c[=<command> [arg 4] [arg 5] ... DOCLIS <a.f.n.> [z_opt] /e=<command> [arg 4] [arg 5] ... Returns Nothing Errors to Standard Error The DOCLIS utility scans source file(s) for the DOCZ header(s) it contains and extracts the library name, module name(s), file name, and supported platform names. The ambiguous file name, a.f.n., may be matched to zero or more files in one or more directories. The output is normally sent to the screen, but a file may be selected for output by specifying the file name with the /o option. UNIX version note: be sure to quote ambiguous file names containing wildcards, so that the DOCLIS program will perform the wildcard expansion instead of the Shell. If the /c option is specified, the DOCLIS utility runs DOCXL for every module found in the specified source file(s), thus automatically updating the Documentation Index File. A post-processing command may also be specified, with the /c option switch: the command may be a command file or program to which will be passed (1) the library name, (2) the module name, (3) the source file name, and any additional arguments on the DOCLIS command line. The /e option is an alternate form of the /c option, specifying that you do not wish to run DOCXL for each module; only the specified command. You may wish to use the post-processing command to update your version control library with a module added to the Documentation Index File, or to relocate the file to the DOCZ source directories. The EXAMPLES section contain command files illustrating this usage. 86 DOCZ PROGRAM REFERENCE For an explanation of the [z_opt] command-line option, see "SELECTING OPTIONS: Specifying Command Line Options." 87 DOCZ PROGRAM REFERENCE DOCLOG Examine/Search the DOCZ transaction log file Arguments DOCLOG [z_opt] Returns Nothing Errors to Standard Error The DOCLOG program allows scanning of the DOCZ transaction/error log. When DOCLOG is invoked, the last entry in the log will be displayed initially. The following commands may be used to navigate through the log: + forward display the next entry - reverse display the previous entry Q Quit quit the DOCLOG program L Last display the last entry F First display the first entry N Ent. No. display the entry number prompted for R Report generate a report The following is an example of a display for a log entry: Entry Number: 2013/3259 Program: DOCXL Date/Time: Thu Jan 24 21:44:55 1989 (6 days ago) User ID: toolz:todd Process ID: 6231 Error Level: WARNING Message: DOCHLP not found : (+)forward, (-)reverse, (Q)Quit, (L)Last, (F)First, (N)Ent.No., (R)Report Press choice: The Entry Number label displays the entry number of the current entry being viewed, and the total number of entries in the log. The Program is the DOCZ System program that produced the log entries (not all DOCZ programs write entries to the log). The Date/Time is the date (in the current date format) and time that the entry was added to the log. The User ID is the I.D. (including nodename) of the User who was running the program that produced the log entry. The User ID will contain both the node name and the username (see "SELECTING OPTIONS" for the MSDOS version). The Process ID is the I.D. of the process owning the program 88 DOCZ PROGRAM REFERENCE that produced the log entry. The Error Level is the severity of the message (Informational, Warning, Error, or Fatal). And, Message is the message describing the log entry. The Report facility provided by DOCLOG allows one ore more log entries to be "dumped" to a file in the same format as they are displayed on the screen. When R is selected, you will be prompted for a starting and ending entry number, as well as the name of the file to which you wish to write the report. Note: logging must be enabled for the transaction log to contain any entries. See the section on "OTHER FEATURES, TRANSACTION LOGGING" for information on enabling logging. For an explanation of the [z_opt] command-line option, see "SELECTING OPTIONS: Specifying Command Line Options." 89 DOCZ PROGRAM REFERENCE DOCMAN View the on-line DOCZ User Manual Arguments DOCMAN [/m] Returns Nothing Errors to screen The DOCMAN program is an interactive on-line documentation viewing utility for the DOCZ System. DOCMAN allows the user to pick a subject from a subject menu for which one or more pages of manual text will be displayed. The subject menu features all major DOCZ topics. Menu items are selected by entering the subject, but only as many characters required to make the subject unique are required. As the text for a subject is displayed, the user may scroll backwards and forwards through the text using the scrolling keys displayed on the screen (specific keys may differ between platforms). The /m option is provided on those platforms on which a color display is implemented. The use of color may be defeated by use of the /m monochrome option. 90 DOCZ PROGRAM REFERENCE DOCLEARN Run the DOCZ Tutorial Arguments DOCLEARN [/m] Returns Nothing Errors to screen The DOCLEARN program is an interactive on-line tutorial for the DOCZ System. DOCLEARN allows the user to pick a subject from a subject menu for which one or more pages of tutorial text will be displayed. The subject menu features all major DOCZ topics. Menu items are selected by entering the subject, but only as many characters required to make the subject unique are required. As the text for a subject is displayed, the user may scroll backwards and forwards through the text using the scrolling keys displayed on the screen (specific keys may differ between platforms). The /m option is provided on those platforms on which a color display is implemented. The use of color may be defeated by use of the /m monochrome option. 91 DOCZ UTILITIES REFERENCE PSET Maintain/use printer interface database Arguments PSET <token> [token] ... [token] Send output to default printer PSET <token> [token] [/D=nnnnn] Send output to printer/queue nnnnn PSET [tokens] /O Send output to standard output PSET [tokens] /O=nnnnn Append output to file nnnnn PSET ? Display all tokens PSET /E Edit the printer sequences PSET /U=nnnnn Send dump of all sequences to file nnnnn PSET [token] [/T=ww/hh] Print test pattern, ww width/hh height PSET /AI=<input ASCII transport file> Read and merge a PSET database transported from another system PSET /AO=<output ASCII transport file> Output a transport file containing the PSET database 93 DOCZ UTILITIES REFERENCE Returns Nothing Errors to Standard Error The PSET utility provides a general-purpose printer feature selection mechanism and a program interface to a printer control sequence data base. Printer features are identified by a seven-character token. Each token is accompanied by a feature description, and the actual escape sequence required by the printer. Tokens are added to the PSET database, PSET.DAT, using the PSET editor, or by running the PCODE utility. If invoked with ? as the only argument, all installed sequences are displayed by token name and description (the ? must be quoted in the UNIX version). If one or more tokens are passed on the command line, the corresponding sequences are transmitted to the default printer. If PSET is invoked with no arguments, a usage prompt is displayed. The /d option is used to specify a printer or queue other than the default. The /o option is used to specify the output device for output or a file. The /u option performs a displayable ASCII dump of all installed sequences. If no name is specified after the /u option, the default printer is used for output. The /t option sends a test pattern to the output device with ww characters per line and hh lines per page. If no arguments are specified for the /t option (PSET /T), a 80 x 66 pattern is generated. If the /e option is specified, the PSET interactive editor is invoked. The PSET editor allows the user to install and/or modify sequences, and it utilizes help messages to guide the user through installation. If no previous PSET.DAT exists on your system: MSDOS: in the search path UNIX: in the search path VMS: in DOCDAT then PSET will create the file in the current directory. Once the PSET file has been created, you must move PSET.DAT to the directory listed above. The current maximum number of sequences that PSET can accommodate is 127. As sequences 94 DOCZ UTILITIES REFERENCE are added, insure that consecutive sequences are installed, i.e. no consecutive sequence numbers may be uninstalled. Operation of the PSET editor is self documenting and will not be further documented here. The /ao option will cause the PSET program to produce an ASCII transport file under the name specified. This file may be transported to another system to be read by PSET using the /ai option. On the system using a transport file as input, a check is made in the local PSET database for duplicate tokens in the transport file, and, if a duplicate is found, the token from the transport file is ignored. 95 DOCZ UTILITIES REFERENCE For tokens specified in the PSET printer database: S The maximum token length is 7 characters, feature description is 31, and output sequence is 17. S Tokens that begin with the underscore character ('_') are reserved for use by Software Toolz. utilities. S Printer sequences may not contain ASCII NULs (try hex 80 instead). If the sequence MUST contain a NUL character, it cannot be supported by this program. See also the PCODE utility. Note that long search paths or directories in your search path that contain many files may cause disk thrashing whenever the PSET reference file is needed (as when DOC is run). 96 DOCZ UTILITIES REFERENCE PCODE Install the PSET database for a particular printer Arguments PCODE [directory for PCODE.DAT] Returns Nothing Errors to Standard Error The PCODE utility provides the printer interface utility, PSET, with a set of features for many popular printers. If PCODE.DAT is not in the current directory when PCODE is run, the directory containing PCODE.DAT must be passed on the command line. PCODE.DAT is a text data file containing the printer database for a number of popular printers. This program is interactive and menu-driven. The features that PCODE currently supports: SET set printer RESET reset printer 17 CPI 17 characters per inch 10 CPI 10 characters per inch 12 CPI 12 characters per inch 8 LPI 8 lines per inch 6 LPI 6 lines per inch DOUBLE WIDTH ON enter double width DOUBLE WIDTH OFF exit double width BOLD ON bold on BOLD OFF bold off UNDERLINE ON underline on UNDERLINE OFF underline off DOUBLE STRIKE ON double strike on DOUBLE STRIKE OFF double strike off ITALICS ON italics on ITALICS OFF italics off SHADOW PRINT ON shadow print on SHADOW PRINT OFF shadow print off 97 DOCZ UTILITIES REFERENCE DOCZ currently uses only BOLD and UNDERLINE attributes when formatting documentation. Future versions of DOCZ may incorporate additional character attributes. S beware that some printers do not allow certain combinations of attributes. S when updated by PCODE, PSET.DAT does not need to reside in the current directory: MSDOS and UNIX versions: the environment PATH will be searched for PSET.DAT. VMS version: PSET.DAT must reside in the data directory, pointed to by DOCDAT. The PCODE utility allows the selection of character attributes from the printer database reference file, PCODE.DAT, which is supplied with the DOCZ distribution. The user can select from a numbered list of printers by specifying the number in the list or the first unique characters of the name in the list. If the list is too large to display on one screen, it will be frozen until the user presses [RETURN] or chooses a printer. Once a printer has been chosen, installation is then confirmed by the user, and the required character attributes are installed in the printer database file, PSET.DAT. The installation for some printers may produce a "Feature not provided" warning message, but unless the feature is BOLD ON, BOLD OFF, UNDERLINE ON, or UNDERLINE OFF, the warning may be ignored. Other printer features are provided with the printer database reference file, and these features may be invoked by specifying their tokens as initialization sequences in the Configuration File, DOCZ.CFG. The PSET utility can be used to examine the sequences installed in the printer database. Tokens with names starting with the underscore character (_) are installed with the PCODE utility. The PCODE utility can also optionally send a test pattern to the attached printer using the sequences installed by the user. The PCODE.DAT file need remain on the system only if the user wishes to reinstall the printer database with a new printer from the printer database reference file. 98 DOCZ UTILITIES REFERENCE CALCDATE Display current date in local date format Arguments calcdate [date] [/o=output file] [+/- days] Returns Nothing Errors to Standard Error The calcdate utility produces the current date in the local date format utilized by the DOCZ System for use in date comparisons. The display screen is used for output, unless an optional output file is specified. If a valid date is passed on the command line, an optional negative or positive offset may be specified to apply to the specified date. If a negative or positive offset is specified with no date, it will be applied to the current date before is displayed. Examples calcdate display today's date calcdate +1 display tomorrow's date calcdate -5 display the date five days ago calcdate 7/8/89 +10 display the date ten days past 7/8/89 Note that the calcdate utility uses the date format established by the System Manager for the DOCZ System. See the section on Date Formats for more information. Also, see the docrevs.sh example Shell script for an example of the usage of the calcdate utility. 99 DOCZ UTILITIES REFERENCE REFORMAT Reformat a text data file into print image Arguments reformat <input file> <output file> [opt] Options: /s=<width> Column width separator size /jr Justify right /jc Justify center /t Use TABs to align Returns EXITNORMAL on success, EXITBAD if options are not properly specified or files cannot be opened. Errors to Standard Error The REFORMAT utility takes text data files and reformats into columnar output for printing. Text data files are a common format to most DOCZ programs and utilities. The REFORMAT utility allows those files to be printed in a more readable fashion. The column width will be determined by the widest field in the column. The maximum number of columns is 32. Options are: /s=<width> Instead of 1 + the maximum field size, use <width> + the maximum field size as the column separator width /jr Use right justification on the columns instead of left justification (the default) /jc Use centering justification on the columns instead of left justification (the default) /t Use TAB characters (instead of spaces) to left justify the columns 100 DOCZ UTILITIES REFERENCE The default column width is one plus the width of the widest field in that column; this may be overridden with the /s option. Left justification is the default and may be overridden by /jr and /jc. The /s option will work in conjunction with /jr and /jc, but not with /t, which is the option to left-justify the columns using TABs. 101 DOCZ UTILITIES REFERENCE FILLS See if a file is space-filled or tab-filled Arguments FILLS <a.f.n.> [a.f.n.] ... [a.f.n.] Returns Nothing Errors to Standard Error The FILLS utility views the leading characters of lines in text files and determines whether they are TABs or SPACEs. 102 DOCZ UTILITIES REFERENCE DETAB Expand TAB characters to spaces Arguments DETAB <a.f.n.> [a.f.n.] [a.f.n.] ... [/tab stop] Returns Nothing Errors to Standard Error The DETAB utility will expand all of the ASCII TAB characters in a file to a pre-determined number of spaces. The default number of spaces to expand is 8, but any number can be optionally specified. 103 DOCZ UTILITIES REFERENCE RETAB Convert spaces to TAB characters Arguments RETAB <a.f.n.> [a.f.n.] [a.f.n.] ... [/tab stop] Returns Nothing Errors to Standard Error The RETAB utility converts text files aligned with spaces by converting spaces to an equivalent number of requird TAB characters. The default "tab_stop" is 8. Analyse the source code you are re-tabbing for the correct value of "tab_stop." 104 ERROR MESSAGES 1k of memory could not be allocated for the banner! Facility: DOC Memory could not be allocated while trying to write the cover page <argument> is an invalid argument! Facility: DOC, DOCXL, DOCHBLD You have passed an invalid argument to the program. <argument> is an unknown argument! Facility: DOCHBLD You have passed an invalid argument to the program. <argument> argument not recognized! Facility: DOCXL The user has specified an invalid (possibly misspelled) argument. <argument> is not valid as an option! Facility: DOCXL The user has specified an invalid option. <argument> specifier unknown! Facility: DOCXL An argument specifier has been specified that is not recognized <file name> -> <file name> rename failed! Facility: DOCXL, DOCXLU During a Documentation Index File rebuild, a temporary file could not be renamed to a permanent file. <index file> lock failed! Facility: DOCXL Locking of the Documentation Index File failed <index file> unlock failed! Facility: DOCXL Unlocking of the Documentation Index File failed <library name> is an invalid library name Facility: DOC, DOCXL The user has specified a library name on the command line either too long in length or containing invalid characters. <module name> is an invalid module name Facility: DOC, DOCXL The user has specified a module name on the command line either too long in length or containing invalid characters. <module name> module documentation not found! Facility: DOCHBLD No documentation for the specified module name was found in the source file being scanned. 105 ERROR MESSAGES <module name> not found! Facility: DOCHELP The module name requested by the user could not be found in the help library. <number> bytes could not be allocated! Facility: DOC, DOCHELP, DOCHBLD A memory allocation failed due to lack of free memory. VMS check related system/account parameters. <option> is wrong for argument <argument number> Facility: DOCXL The user has specified an option incompatible with the other arguments. <parameter> not recognized as a DOC parameter! Facility: DOC The user has coded a DOC parameter in the Documentation Header that is not valid. <parameter> has no arguments! Facility: DOC, DOCHBLD The named parameter specified in the documentation header has no arguments Application Keyword Index sort failed! Facility: DOC An attempt was made to use an external sort program to sort an intermediate file containing the Application Keyword Index, and the sort failed because (1) the sort program cannot be found, or (2) there is not enough available memory to perform the sort, or (3) the sort program does not work properly. Bad date! Facility: DOC The Documentation Header contains a revision or fix date of an invalid format. Cannot call the command processor for sort! Facility: DOC Either a call to the system command processor failed (possibly because it does not exist in the current search path [MSDOS]) or the command processor itself could not find the SORT utility in the current search path. VMS requires SYS$SYTEM:SORT.EXE. UNIX requires sort in the search path. MSDOS requires SSORT in the search path. See INSTALLATION. Cannot determine DOCZ environment! Facility: DOC, DOCHBLD, DOCHELP, DOCLOG, DOCXL, DOCXLED, DOCXLU, DOCMAN, DOCLEARN The environment variables and/or logical names have not been provided for the DOCZ System. 106 ERROR MESSAGES Cannot get DOCZ symbols! Facility: DOC, DOCHBLD, DOCHELP, DOCLOG, DOCXL, DOCXLED, DOCXLU, DOCMAN, DOCLEARN The environment variables and/or logical names have not been provided for the DOCZ System. Cannot open <file name>! Facility: DOC, DOCXL, DOCXLU The file cannot be opened in an unspecified mode. Check file permissions. Cannot open <file name> for output! Facility: DOCXL, DOCHBLD, DOCXLU The file could not be opened for writing. Check file protection. Cannot open <file name> for input! Facility: DOCXL, DOCHBLD, DOCXLU, DOCLOG, DOCLIS, DOCGET The file could not be opened for reading. Check file protection. Cannot open <Documentation Index File spec> for input! Facility: DOCXLED File cannot be found or opened. Check logical names/symbols or file permission. Cannot open help file: <filename> Facility: DOCHELP The compiled help library, DOCHELP.HLP, could not be found in the Reference Directory. Cannot open <filename>! Facility: DOC, DOCXL, DOCHBLD, DOCXLU The named file cannot be opened either because it does not exist (files opened for read) or process privilege does not allow access to the file or directory. Cannot read in Documentation Index File! Facility: DOC, DOCHBLD The Documentation Index File cannot be read, possible due to file protection violation. CANNOT READ! Facility: DOCXLED Unexplained read failure in the Documentation Index File. Cannot rename <file name> to <file name>! Facility: DOC A call was made to the rename system service that failed. This can fail for the same reasons that a Unix mv, an MSDOS REN, or a VMS RENAME can fail. Check for the pre-existence of the destination file or permissions. 107 ERROR MESSAGES Cannot read: <file name>! Facility: DOCHBLD The named file cannot be read. Check file protection. Cannot read file! Facility: DOCLOG The DOCZ log cannot be read. Check file protection. CANNOT SEEK! Facility: DOCXLED Unexplained seek failure in the Documentation Index File. Cannot seek in Documentation Index File! Facility: DOC A seek failure has occurred in the Documentation Index File for an unknown reason. Cannot seek in help file! Facility: DOCHELP A seek in the help library file has failed, possible due to the file header being corrupted. Cannot seek in file! Facility: DOCLOG The DOCZ log cannot be read. Check file protection. Cannot seek to <file offset> Facility: DOC, DOCHBLD A seek in a source file failed for an unknown reason. Cannot seek to beginning of module index! Facility: DOCHBLD While building the on-line help library, an error occurred in a seek in the output file. Cannot validate date: <date>; check date format: <date format>! Facility: DOCXL, DOCXLED A date was specified on the command line or embedded in the documentation header that does not match the date format string. <command> failed as a command! Facility: DOCLIS The specified command was to be executed but could not because (1) the command processor could not be loaded, (2) it is an invalid command, (3) the command could not be found, (4) or there is not enough memory. 108 ERROR MESSAGES Configuration File specifies printer: <printer name>; but PSET specifies: <printer name>! Facility: DOC The printer named in the PSET database and DOCZ Configuration File are different. This is a permissible condition in some environments using alternate Configuration Files. Date format string does not match date format! Facility: DOC A date was specified on the command line or embedded in the documentation header that does not match the date format string. Could not lock Documentation Index File! Facility: DOCXL, DOCXLU An attempt to write lock a record in the Documentation Index File has failed. The record may be locked by another program. Could not call convert-to-stream (VMS version) for <filename> Facility: DOC, DOCHBLD The named file could not be converted from its present format to a Stream file either because the VMS Convert routines failed or the DOCDAT: directory does not contain STREAM.FDL. Could not read <number> entries in key index! Facility: DOCHBLD A read during a help file build caused an error. Could not write <number> entries in key index! Facility: DOCHBLD A write during a help file build caused an error. Date (date) format error! Facility: DOC A date was specified on the command line or embedded in the documentation header that does not match the date format string. DOC-RPT_INIT-W-PSET parameter problem! Facility: DOC Either a PSET parameter was specified in the Configuration File that does not exist in the PSET database, the PSET database has never been built, or the PSET database file (PSET.DAT) cannot be read. Documentation Index File is empty or does not exist! Facility: DOCXLU The Documentation Index File is empty or does not exist! Documentation Index File has no entries for <library name>! 109 ERROR MESSAGES Facility: DOC A library name was specified for which the Documentation Index File contains no entries. Documentation Index File locking error! Facility: DOCXLU An attempt to lock the Documentation Index File failed. Check VMS image privileges. Check MSDOS sharing. DOCZ log is empty! Facility: DOCLOG There are no entries in the log. Check to see that logging is enabled (via the Configuration File). This message will be displayed when DOCLOG is run immediately after installation, and no DOCZ programs have yet had the opportunity to make log entries. Empty field <parameter name> is required! Facility: DOC A required parameter in a documentation header was specified without any arguments. FIELD: <parameter name>, count overflow - current=<number> - max=<number>! Facility: DOC, DOCHBLD The Documentation Header contains a parameter that may occur multiple times, but the user has exceeded the allowable number of occurrences of the parameter. Field count overflow! Facility: DOCHBLD The Documentation Header contains a parameter that may occur multiple times, but the user has exceeded the allowable number of occurrences of the parameter. File too big or sort utility not found! Facility: DOC An attempt was made to call an external sort program to sort an intermediate file, and the sort failed because (1) the sort program cannot be found, or (2) there is not enough available memory to perform the sort, or (3) the sort program does not work properly. File write failure on <file name>! Facility: DOCXL, DOCXLU An attempt to write to a file failed. Check file protection or device full. Incomplete set of command line arguments! Facility: DOCXL The requisite set of command line arguments was not properly specified. Index write for <module name> failed! 110 ERROR MESSAGES Facility: DOCHBLD An attempt to write to the Documentation Index File failed. Check file protection. <Index File> lock failed! Facility: DOCXL An attempt to lock the Documentation Index File failed. Check VMS image privileges. Check MSDOS sharing. <Index File> unlock failed! Facility: DOCXL An attempt to unlock the Documentation Index File failed. Check VMS image privileges. Check MSDOS sharing. Invalid Date! Facility: DOCXL The user has specified an invalid date. Invalid modification date/time! Facility: DOCXLED Date or time entered in an improper format. See DOCZ section on Conventions. Invalid U record in Configuration File! Facility: DOC, DOCXLU, DOCHBLD An error in the user-supplied U record in the Configuration File was detected. See DOCZ section on Specifying Options. <library name> is not valid as a DOC library name Facility: DOC The user specified a module name containing invalid characters (the user may have specified a file name instead of a library name). Library name does not match current library <library name> Facility: DOC The documentation header in the source for the module contains a .LIBRARY parameter with a different library name than the name specified on the DOC command line. Library, module, or file not specified! Facility: DOCXL An add/update was requested without specifying the library name, module name, or source file name. Line number <number> contains an unrecognized parameter! Facility: DOC The DOCZ Configuration File contains an invalid parameter on the specified line. Memory allocation for permutation failed! Facility: DOC 111 ERROR MESSAGES The memory that must be allocated to perform the text permutation on the module descriptions failed. Memory may be limited in your system. Missing <DOC parameter> field is required! Facility: DOC A required DOC parameter is missing in the Documentation Header. Month is negative or greater than 12! Facility: DOC An attempt to validate a date failed because the month was out of range. <module name> is an invalid module name in <file name> Facility: DOC The specified module name contains invalid characters (the user may have specified a file name instead of a module name). <module name> is an invalid module name! Facility: DOCXL The specified module name contains invalid characters (the user may have specified a file name instead of a module name). <module name> NOT FOUND FOR <library name> LIBRARY! Facility: DOCXLED A module was specified in a search, and the module could not be found. Needed to read <number> items but less were read! Facility: DOCHELP The help library file has not been formatted correctly. It could either be damaged, or the original documentation was not formatted correctly. No files match <ambiguous file name>! Facility: DOCLIS An ambiguous file name was specified to DOCLIS for which there were no matches. No FIXES/REVISIONS within date range for <library name>! Facility: DOC Either a Fix Notice or Revision Notice was selected but no Fix or Revision dates embedded in the module documentation qualify. NO modules found! Facility: DOC No modules matching the command line criteria could be found in the Documentation Index File. No modules found for help library! 112 ERROR MESSAGES Facility: DOCHBLD No modules could be processed to build a help library. The Documentation Index File may be empty. No module documentation found in <source file>! Facility: DOC There were no modules for the current library found in the named source file. Check the .LIBRARY field. No <report type> for this library! Facility: DOC One of the various report types was selected for which there were no qualifying modules. No occurrences of <module name> in <library name> library located! Facility: DOCXL A user-specified search has failed to find any modules. Not enough arguments Facility: DOCXL Not enough command line arguments have been specified. Not found! Facility: DOCHELP The user specified a module name not in the documentation help library. NOT FOUND: <file name> Library: <library name> Module: <module name> Facility: DOCHBLD The source file for the specified module could not be found. Number of days is incorrect for the month! Facility: DOC A date validation revealed an ill-formatted date. Only <number> DOC parameters found for <module name> in <source file name>! Facility: DOC The program could not detect enough DOC parameters in the source file for a valid Documentation Header. <option> is not valid as an option! Facility: DOCXL The option was specified on the command line, but it is invalid. <option> specifier unknown! Facility: DOCXL The invalid option was specified. OUT OF RANGE! Facility: DOCXLED 113 ERROR MESSAGES You have attempted to select an entry before the first entry in the file or after the last entry in the file. Parameter in DOCZ.CFG specified too many times! Facility: DOC The specification of a parameter exceeded the maximum allowable occurrences. Permuted description sort failed! Facility: DOC An attempt was made to call an external sort program to sort an intermediate file containing the permuted module descriptions, and the sort failed because (1) the sort program cannot be found, or (2) there is not enough available memory to perform the sort, or (3) the sort program does not work properly. PSET parameter problem Facility: DOC You have specified a PSET parameter that does not exist in the PSET database or the PSET database file cannot be opened. Read error in help file! Facility: DOCHELP The help library file has been damaged, mis-formatted, or file protection has been applied to it. Report formatter initialization failure Facility: DOC Either memory could not be allocated or the output print file could not be opened for write. Report formatter closing failure Facility: DOC An exit PSET parameter has been specified that is not in the PSET database or the PSET database file could not be opened. SEARCH ABORTED! Facility: DOCXLED User pressed a key while a search was in progress (not an error). Second command must be an option! Facility: DOCLIS A file specification may only be the first argument to DOCLIS. SYSLCK privilege required! Facility: DOCXL, DOCXLU The DOCXL image (VMS version) must be installed with the SYSLCK privilege or must be run by accounts with the SYSLCK privilege. 114 ERROR MESSAGES The day is negative! Facility: DOC The date could not be validated for the specified reason. The <file name> Configuration File is not formatted correctly! Facility: DOC The Configuration File is garbled. The font file BANNER.DAT could not be found! Facility: DOC In all versions except MSDOS, the font file (BANNER.DAT) must be installed in the data directory or search path. The font file BANNER.DAT could not be read! Facility: DOC The font file (BANNER.DAT) was found but could not be read. The O and V options are incompatible! Facility: DOCHBLD The user has specified mutually exclusive command options to DOCHBLD The PSET database does not exist or does not contain character attributes! Facility: DOC Character attributes cannot be determined for the printer specified in the Configuration File because the PSET.DAT file does not exist, cannot be found in the search PATH, or is empty. The year is negative! Facility: DOC The date could not be validated for the specified reason. Tried to read more than maximum no. (<number>) of references! Facility: DOC The users library contains more modules than is allowed for the memory allocated on the user's system. See INSTALLATION for information on the maximum number of modules allowed in a single library displayed by number. Upper Case: <library>-<module>-<file specification> Facility: DOCXLU While outputting an ASCII Transport File on an MSDOS or VMS system, upper case characters in a file specification were detected; a potential problem if transported to a Unix system. Version Control fetch of <filename> failed! Facility: DOC, DOCHBLD 115 ERROR MESSAGES (VMS version)The module is not contained in the CMS library pointed to by DOCSRC, or CMS produced an undefined failure on a fetch. Wrong arguments Facility: DOCXL The user has specified the wrong combination of arguments. 116 OTHER FEATURES Directory Layout The DOCZ System programs neither store source files nor do they create any directories in which source files are stored. The path to a source file is stored in the Documentation Index File. The file name specified in that path may be specified either with or without a directory name. If no directory name is specified with the file or there is no U record in the Configuration File that applies to the current module, the default condition is assumed: (1) The root directory for such source files will be pointed to by the DOCSRC symbol or logical name. (2) The file will be located in a sub-directory of the DOCSRC root directory, the name of which will be the name of the library (in upper case). For example, if a module fred were stored in the fred.c source, and specified to DOCXL as in: DOCXL clib fred fred.c The default location of the fred.c source file would be: VMS: [equivalent_of_DOCSRC.CLIB]FRED.C MSDOS: %DOCSRC%\CLIB\FRED.C UNIX: $DOCSRC/CLIB/fred.c If a directory specification is specified with the source file, that full specification will be used to find the file. In the VMS version (using CMS version control), if the subdirectory of the library name is not a valid CMS library, the directory pointed to by DOCSRC will be tested for validity as a CMS library. If DOCSRC points to a valid CMS library, source files will be fetched from that library. This feature allows CMS users to combine all source files in all libraries into one CMS library (should they choose to do so). 117 OTHER FEATURES Cross-Platform Development The Documentation Index File Remember, that if no directory is specified with a file name in the Documentation Index File or the default file specification is not overridden with a U record in the Configuration File, DOCZ assumes the default condition and internally generates a path to the file based on the DOCSRC symbol (or logical name). On the other hand, a directory name may be stored with the full file specification for a source module, forcing DOCZ to bypass the use of the DOCSRC symbol. This feature is especially useful when DOCZ documentation is found in headers that must be included by the compiler, and the development environment is configured such that there is a header directory separate from the location used for the storage of DOCZ source files. Specifying a directory name can pose an interesting challenge in a multi-platform development environment, as directory specifications do not generally transport from one operating system to another. For those instances where full file specifications need to be specified in the Documentation Index and transportation of the Documentation Index File from one hardware platform to another is necessary, the DOCZ system allows symbol substitution for the directory portion of a complete file specification. If a valid file name is preceded by a token surrounded by a dollar ($) sign, an attempt to translate that token, using the environment symbols or logical names, into a directory specification will be performed. For example: assume a symbol (or logical name) is defined: VMS: SRCFILES == "$2$DUA21:[USER.PROJECT.SOURCE]" or DEFINE/PROCESS SRCFILES - $2$DUA21:[USER.PROJECT.SURCE] MSDOS: SET SRCFILES=c:\user\project\source UNIX: SRCFILES=/usr2/project/source export SRCFILES 118 OTHER FEATURES And, the module were added to the DOCZ system by: DOCXL clib fred $SRCFILES$fred.c or (in the Unix version, where the last argument must be quoted to preserve the '$' sign being passed to DOCXL): DOCXL clib fred '$SRCFILES$fred.c' When the module is needed by the DOCZ system, the SRCFILES symbol will be translated to the required directory specification. This feature will allow you to use the same Documentation Index File transported to different computers using different file naming conventions when you choose to specify full file specifications in the Documentation Index. See the documentation DOCXLU for information on generating ASCII Transport Files for the Documentation Index File. ASCII Transport Files for the Documentation Index File are produced by the DOCXLU command. An output file is generated using the /ao option, and an input file is read using the /ai option. The method used for physically transferring the ASCII files from one platform to another is totally dependent on your site's environment and local network, and can be achieved in several ways. In all cases, insure that Transport files are transported as "text" files. 119 OTHER FEATURES DOCZ Help Libraries ASCII Transport Files for on-line help libraries can be produced by the DOCHBLD command. An output file is generated using the /ao option, and an input file is read using the /ai option. With this capability, in a cross- platform development environment, the source files need be kept on only one platform, but the help libraries can be made available to developers on all platforms. Note: the DOCZ System must be licensed on all platforms. The ASCII Transport File output of the DOCHBLD program can be combined with the ASCII Transport File from other platforms. It can also be combined with the on-line help library that comes with the DOCZ System. Simply use the /ai option to combine ASSCI Transport Files as input to DOCHBLD. For example, to produce an ASCII Transport File for an on- line help library for all modules documented by your local DOCZ System: dochbld /ao=help.txt Then, combine the ASCII Transport File with DOCHELP.TXT, which is distributed with the DOCZ System: Unix: dochbld -ai=help.txt,$DOCSRC/dochelp.txt VMS: dochbld /ai=help.txt,DOCSRC:dochelp.txt MSDOS: dochbld /ai=help.txt,%DOCSRC%\dochelp.txt Which will build a new on-line help library using the contents of both help.txt and dochelp.txt. To combine your local on-line help library with both the DOCZ help library and the Standard C Library on-line help, use the following command(s): Unix: dochbld - ai=help.txt,$DOCSRC/dochelp.txt,$DOCSRC/c.txt VMS: dochbld /ai=help.txt,DOCSRC:dochelp.txt,DOCSRC:c.txt MSDOS: dochbld /ai=help.txt,%DOCSRC%\dochelp.txt,%DOCSRC%\c.txt 120 OTHER FEATURES Version Control None of the DOCZ System programs actually update source code using the DOCZ supported version control software; this is a responsibility of the site. However, the DOCZ System provides tools to help automate such activities. One such tool is the DOCLIS command, with which a source add or update can be automated through the calling of command files written for the site's development environment by the local administrator. See the DOCLIS documentation for the implementation of this feature and the EXAMPLES in this manual for suggestions on how to implement automation using this feature. Whenever possible, source code for the examples are included on the distribution media for use and modification by the DOCZ System administrator. Cross-Platform Transportation Summary Export the Documentation Index File DOCXLU /ao=<transport file> Import the Documentation Index FIle DOCXLU /ai=<transport file> Export the Help Library DOCHBLD /ao=<transport file> Import the Help Library DOCHBLD /ai=<transport file> Export the printer database PSET /ao=<transport file> Import the printer database PSET /ai=<transport file> 121 OTHER FEATURES Using DOCZ WIthout Source Code The DOCZ System can be used to document routines and programs for which you do not have the source code. The documentation header can be contained in a text file stored with the other members of the library. In fact, any number of modules can be documented in this manner, including libraries supplied with compilers. Combining such documentation with the DOCZ System provides a sole referencing source for all developers, including on-line help. The documentation for such modules can either be typed by hand or scanned-in, provided you have the proper equipment and provided that the scanning of the documentation does not violate copyrights. 122 HISTORY DOCZ 1.0 4/86 31469 DOC and DOCXL first release, VMS 5/86 31472 Add REVISION Notice report capability to DOC 6/86 31528 Add user-specified printer set-up capability 7/86 31559 Cover tutorial/introduction feature introduced to DOC 7/86 31562 Increased size provision for module names and file names 8/86 31569 VMS automatic conversion to Stream_LF introduced 12/86 31702 DOC parameters converted from numeric to English DOCZ 1.1 1/87 31726 MSDOS version introduced 7/87 31906 CMS support introduced (VMS version) 8/87 31953 Add capability to specify DOCZ directories via CLI symbols 9/87 31971 Add on-line help library build for VMS version 9/87 31983 Add automatic installation for popular printers 9/87 31987 Add support for printer character attributes in documentation 10/87 32017 Add provision to locate source in multiple named directories DOCZ 1.3 1/88 32109 Add FIX Notice report capability to DOC 1/88 32110 Add Documentation Index File rebuild capability 2/88 32128 Add documentation summary feature to DOC 2/88 32127 Add FORTRAN, BASIC, COBOL, and other language support 3/88 32157 Add Documentation Index File editing capability 5/88 32207 Add capability to specify multiple individual modules to DOC 6/88 32240 Add capability for unique user-specified source code format 7/88 32275 Add on-line help program for all versions 7/88 32290 MSDOS BRIEF support introduced 8/88 32311 MSDOS Installation Kit introduced 9/88 32348 Add capability to verify presence of entire library source code 9/88 32351 Add Documentation Index locked notification feature 123 HISTORY DOCZ 1.4 9/88 32326 UNIX version introduced, first built on AT&T 3B2, SysV.3.1 9/88 32351 MSDOS network version introduced 10/88 32356 UNIX sccs support introduced 11/88 32387 DOCZ built on XENIX-286, Rel. 2.2.2 11/88 32402 Add capability to specify multiple Application Keywords 12/88 32417 Add ASCII Transport facility for on-line help libraries DOCZ 1.5 1/89 32448 Totally revised and typeset DOCZ System documentation 1/89 32463 DOCZ built on Convergent S640, SysV.2.5 1/89 32477 VMS VMSINSTAL Installation Kit introduced 1/89 32478 Add ASCII Transport output for Documentation Index File 2/89 32479 Add capability to specify source code language via file extensions 2/89 32499 Add current date defaulting to all programs 3/89 32515 Introduce DOCXLU utility 3/89 32529 Unify CLI symbols and logical names across all supported platforms 4/89 32547 Add user specified and European date format support 4/89 32550 DOCZ transaction logging introduced 5/89 32568 DOCZ built on Interactive 386, SysV.3.2 6/89 32602 Source file directory specs made as sub- directories 6/89 32611 DOCLIS utility added 8/89 32696 Added symbol substitution capability 9/89 32689 Added CALCDATE utility 10/89 32754 Added auto-load capability to DOCLIS 11/89 32743 Added ASCII Transport capability to PSET 12/89 32792 Added platform summary to full DOC output 1/90 32819 Removed terminal dependence from DOCXLED and PCODE 1/90 32820 Added permuted description to full DOC output 3/90 32886 Added universal support for version control and alternate directory naming 3/90 32897 Added reporting capability to DOCLOG 4/90 32910 DOCZ built on AViiON/DGUX 5/90 32939 DOCZ built on SUN/SPARC DOCZ 1.6 10/90 33129 Added statistics logging 10/90 33131 Added Variable TAB expansion 11/90 33145 Added DOCHELP module description search 124 HISTORY 12/90 33156 Added DOCMAN on-line User Manual 1/91 33185 Added [z_opt] directory specification override 1/91 33190 DOCZ built on NCR 500, 700 3/91 33238 Added FILLS, DETAB, and RETAB 4/91 33270 Added DOCLEARN tutorial 4/91 33285 DOCZ built on IBM RS6000/AIX 8/91 33401 DOCZ built on SCO Unix 125 EXAMPLES Building a Documentation Library The following is a set of MSDOS commands that may be used to add a module named "CMDLINE" documented in the source file "CMDLINE.PAS," and place it in the "ULIB" library: REM move source to source directory COPY CMDLINE.PAS \DOCSRC\ULIB REM add/update Documentation Index File DOCXL ULIB CMDLINE CMDLINE.PAS REM run the documentation DOC ULIB CMDLINE The equivalent commands for VMS (without CMS): ! move source to source directory DOCROOT = F$EXTRACT(0,F$LENGTH(F$TRNLNM("DOCSRC"))-$ 1,F$LOGICAL("DOCSRC")) COPY CMDLINE.PAS 'DOCROOT'.ULIB] ! add/update Documentation Index File DOCXL ULIB CMDLINE CMDLINE.PAS ! run the documentation DOC ULIB CMDLINE The equivalent commands for VMS with CMS: DOCROOT = F$EXTRACT(0,F$LENGTH(F$TRNLNM("DOCSRC"))- 1,F$LOGICAL("DOCSRC")) CMS SET LIBRARY 'DOCROOT'.ULIB] ! insert source in version control library CMS CREATE ELEMENT CMDLINE.PAS <comment> ! associate group name (optional) CMS INSERT ELEMENT CMDLINE.PAS ULIB <comment> ! add/update Documentation Index File DOCXL ULIB CMDLINE CMDLINE.PAS ! run the documentation DOC ULIB CMDLINE The equivalent commands for UNIX (without SCCS): # move source to source directory mv cmdline.pas $DOCSRC/ULIB # add/update Documentation Index File docxl ulib cmdline cmdline.pas # run the documentation doc ulib cmdline The equivalent commands for UNIX with SCCS: # update version control delta $DOCSRC/ULIB/cmdline.pas # add/update Documentation Index File docxl ulib cmdline cmdline.pas 127 EXAMPLES # run the documentation doc ulib cmdline C Language See strmcpy.c 8086 Assembly See strmcpy.asm VAX11 Assembly See strmcpy.mar MSDOS Batch File See move.bat BASIC Function Requires a Comment String Mask in Configuration File See fake.bas FORTRAN Function Requires a Comment String Mask in Configuration File See upcase.for Pascal Function See cmdline.pas DCL Command File See mailfile.com Bourne Shell Script See cp_r.sh C Language Macro See macro.h Dbase Language Requires a Comment String Mask in Configuration File gtsa.prg 128 EXAMPLES Perl Language See frank.prl DOCZ Automation See DOCREVS.COM DOCZ Automation docrevs.sh DOCZ Automation See DOCSTASH.COM DOCZ Automation docstash 129 EXAMPLES A Sample DOCZ Library As an example for a real DOCZ application, a DOCZ reference manual containing six modules is contained in the file, CSUB.DOC, which was provided by the installation procedure in the DOCSRC directory. The companion source files, also deposited in the DOCSRC directory, are: delstr.asm haspriv.c insert.mar juldate.c macros.h zero.c All listings are examples from real-life DOCZ libraries. This library happens to be a C function library, but the DOCZ System is not limited to any particular language. 130 TECHNICAL DETAILS Documentation Index Record Format The Documentation Index File, DOCXL.DAT, is a sequential, non-indexed flat file with fixed-length records containing both binary and ASCII data. VMS version: The file format is Stream_LF. Each record consists of: 11 character array and NUL terminator - library name 31 character array and NUL terminator - module name MSDOS version: 88 character array and NUL terminator - file spec VMS and UNIX versions: 128 character array and NUL terminator - file spec 4 byte unsigned integer - time/date of last update (in Unix time) 2 byte unsigned integer - date of introduction 1 byte flag indicating a deleted record 1 byte pad Development Language All DOCZ programs were developed in the C Language, and draw on a portable C library developed in Assembly (VMS and MSDOS) and C. 131 TECHNICAL DETAILS Version Control Software Interface VMS version: (Code Management System) has been installed If CMS on your VMS system, the DOCZ installation will detect this (by searching for SYS$SHARE:CMSSHR.EXE) and link to the CMS callable interface. If DOCSRC points to a CMS library directory, modules will be fetched via CMS. If CMS is installed on your VMS system after the DOCZ System is installed, DOCZ will have to be re- installed. The DOCZ System is designed to work either with or without CMS. UNIX version: When a DOCZ module is requested by the DOC program, the source file name is prepended with "s." and a check for a file of that name is made. If a file of that name exists in a sub-directory of the DOCSRC directory or the path specified in the Documentation Index File, an sccs "get" will be performed to fetch the file from sccs. If the file name without the "s." prefix exists instead, it will be used for input to the DOC program. Standard Error Error messages are always directed to Standard Error and may be re-directed (if supported by your operating system). 8.5 x 11 Documentation Size In a recent Usenet survey concerning documentation size, MSDOS, VMS, and UNIX software developers expressed a preference for the standard 8.5 x 11 inch documentation size at a ratio of about six to one. Hence, the DOCZ User Manual has been produced in a size that suits most of its users. Case in Module and Library Names In most environments in which DOCZ is used, case is significant in identifiers. However, in large development environments name clashes are common. Hence, the DOCZ convention to ignore case in identifiers has been adapted to decrease the chances for confusion and error in environments where DOCZ is likely to be used. 132 TECHNICAL DETAILS Some Implementation Requirements Portability One design criteria for the DOCZ System was an ideal cross-platform development environment. Even in single-platform shops, The DOCZ System provides a complete automated code documentation system. But, in multi-platform development shops, it is unique. 133 QUESTIONS AND ANSWERS How is the name "DOCZ" pronounced? It sounds like "docs." How do I delete a module? Run DOCXL with the /x option, naming the library and module. Or, run DOCXLED, find the record containing the module, and change the deleted record field to Y. You may then optionally remove the source from the DOCZ directories, if this is the only module contained in the source. Can I use any parameters other than those listed in the valid parameter table? No. DOCZ recognizes only the listed parameters and considers any others to be typographical errors. Can I use the on-line help system for my Standard Library? DOCZ does not limit you to modules for which you have the source code. Any program, subroutine, or command file can be documented with DOCZ. See the section on "OTHER FEATURES: Using DOCZ Without Source Code." How can I be sure that my DOCZ environment is properly set- up? (1) To verify the presence of required source files, use: DOCXLU /V (2) To examine symbol/logical name settings, options specified in the Configuration File, and other important information about the environment, use: DOCXLU /S (3) To verify the integrity of documentation headers, run DOC once for each library: DOC <library name> Character attributes are not being utilized properly on my printer. Insure that the PSET printer database has been installed for your printer: the PCODE utility is provided for this. If the PCODE utility does not list your printer, use the PSET editor to manually describe each of the sequences required by DOC. See "SELECTING OPTIONS: The Printer Interface." 135 QUESTIONS AND ANSWERS What is the SSORT program that is installed with the MSDOS version? It is a text sorting program with functionality identical to the SORT program found on many MSDOS systems. DOCZ supplies its own sorting program because there is no guarantee that the user will have the MSDOS SORT program installed or that it can be found in their search path. In addition, some vendors supply a SORT program that does not always work as expected. Can I customize headers and footers in the output documentation? No. They are fixed in format. But page width, page length, and margins can be adjusted to suite your needs. See "SELECTING OPTIONS: The Printer Interface." DOCZ is available on a limited number of hardware platforms. When can I expect it to be available on my favorite platform? It depends on how cooperative the platform vendor is, the expense of obtaining the platform, and the level of demand. You should contact Software Toolz with a request to support the platform of your choice. Why is the performance of DOCZ under VMS less than whizzy? Because DOCZ does not make direct calls to VMS system services (such as RMS). This makes the source code for DOCZ much easier to port to other platforms. Do I need to be concerned about file locking? The Documentation Index File is the only file in the DOCZ system in which the same record could potentially be updated simultaneously by more than one process. In multi-user versions of DOCZ it is locked for update for all platforms (including MSDOS if SHARE is installed). My documentation does not look at all like the samples! See "FORMATTING SOURCE CODE: The Parameters for Documentation Headers." Some parameters require single-word arguments, or dates, or arguments on the same line as the parameter. Most output documentation problems arise from a violation of these requirements. 136 QUESTIONS AND ANSWERS If I enable logging, won't the log grow endlessly? No. Every time a program logs to the DOCZ log, the first entry in the log is checked for age. If its age is older than the limit in effect, the log is "cleaned." This operation may occur no more than once each day. See "SELECTING OPTIONS: Transaction Logging." Can I edit the DOCZ log directly using a text editor? Yes, as long as the entries remain in chronological order (for cleaning purposes) and the fields are not rearranged. Can I edit the Documentation Index File directly using a text editor? No. The Documentation Index File is binary, and you can use the DOCXLED program to modify it. You can produce an ASCII Transport File using DOCXLU and that file can be edited directly with a text editor (taking care not to rearrange the fields). Can I invoke DOC once to print all reference manuals? No. DOC must be run once for each library name. I built a help library on one platform and transported it to another. After I ran DOCHBLD against the transported file, DOCHELP displayed garbage. It is quite possible that your transport mechanism modified the transport file in some way. Be sure that your transport mechanism fixes end-of-line (if necessary) and does not affect the file format in any way. The VMS version of DOCHBLD requires Stream_LF files, but if any other format is used for input, it will be automatically converted to Stream_LF by DOCHBLD. On my VMS system, the default text file format is VAR, but DOCZ requires Stream_LF. These files will be automatically converted when needed by either DOC or DOCHBLD for input. CMS does not care which format is used. Some performance losses will be noticed if conversions are required. 137 QUESTIONS AND ANSWERS A DOCZ program blew-up when I gave it a wild-card argument in my Unix version. In some cases, DOCZ programs require wildcard arguments passed to be quoted so that the program can expand the wildcards instead of the Shell. See the documentation for the program. I purchased a single-user version of DOCZ, but now several people want to use it. Your license type can be converted to multi-user with a credit for your single-user license. Contact Software Toolz. If your distribution media required a surcharge (tape), it may be returned to Software Toolz for a credit when new distribution media is issued to you. I purchased DOCZ for one platform, and I want to license DOCZ on another platform in addition. Licenses for additional platforms are available at a discount after the first platform is licensed. Columns are out of alignment in my documentation and on-line help libraries. Use the "Variable TAB" option in the Configuration File to match TAB expansion to your source code editor. I would like to use the PSET program with my other utilities. PSET, and the other DOCZ utilities, PCODE, REFORMAT, FILLS, DETAB, RETAB, and CALCDATE, are independent of the DOCZ environment (they do not use DOCZ environment variables or DOCZ directory naming conventions) and are therefore usable with your other utilities. Why is my disk "thrashing" when I first invoke the DOC program? The DOC program uses the PSET database, PSET.DAT. DOC automatically searches for the file using your search path. If your search path is long or if the directories in your search path (that are searched before PSET.DAT is found) contain many files, the search will produce "thrashing." There are a few features I would like to see added to DOCZ. 138 QUESTIONS AND ANSWERS Can I make a few suggestions? Almost 100% of customer suggestions are incorporated into new releases of DOCZ. Some enhancements may be made immediately, while others may have to be put-off for a later release. ALL suggestions are taken seriously! Where is Ball Ground, Georgia? About 40 miles due north of Atlanta. 139 INSTALLATION Basic Installation The DOCZ System installation is very similar on all of the supported platforms, and consists of the following basic steps: (1) Provide the DOCZ programs in your search path, or (in the VMS version) define the DOCZ programs as foreign commands. (2) Create the DOCSRC default source root directory. (3) Create a sub-directory (to DOCSRC) for each library to be documented with the name of the sub- directory begin the same as the library name (in upper case). (4) Create the DOCREF directory. (5) In the VMS version, create the DOCDAT directory. (6) vide the DOCZ symbols/logical names for DOCZ Pro users. All of the above steps are provided in the installation procedure that is part of the DOCZ Installation Kit. Directories to which DOCZ files are installed may, in all cases, be specified by the installer. Conventional default directory names are supplied, but these can be overridden during the installation. Directories that do not already exist (and their parent directories) will be created. Re-installation/Update The DOCZ installation procedure will check for the presence of configuration files that may already exist in the directories to which you are installing. Files will most likely already exist when re-installing or updating DOCZ. In this case, the installation procedure will warn you about the condition, and ask you for permission to overwrite those files. 141 INSTALLATION Enabling Extended DOCZ Features Optional steps for utilizing extended features of the DOCZ system are: (1) Provide a Configuration File in the DOCREF directory that specifies automatic options. (2) Build a printer feature database using PCODE and/or PSET, and specify the printer features to use in the Configuration File. (3) Enable/disable transaction logging in the Configuration File (enabled for 30 day log retention by default). (4) Automate Fix, Revision, and Introduction Notices via command files. (5) Provide library introduction;s (cover sheets) in the DOCREF directory. (6) Bridge cross-platform development environments using DOCZ ASCII Transport Files. (7) Build an on-line help library with DOCHBLD, to be viewed by users using the DOCHELP utility. (8) Use version control software supported by the DOCZ System to manage source code. (9) Edit the Configuration File to use non-supported directory naming and version control software. 142 INSTALLATION Examples and Support Files getstart.doc guide to getting started quickly dochead.txt generic prototype DOCZ header dochead.cb Brief macro to insert DOCZ header into source code dochelp.m Brief macro for the DOCHELP utility dochelp.txt ASCII Transport File for DOCHBLD utility to build a help library for the DOCZ system fake.bas BASIC source example move.bat MSDOS command file source example cmdline.pas Pascal source example strmcpy.asm 8086 Assembly source example strmcpy.mar 1 Assembly source example VAX1 mailfile.com VAX-DCL source example strmcpy.c C source example cp_r.sh UNIX Shell source example upcase.for FORTRAN source example macro.h C macro example gtsa.prg Dbase example frank.prl Perl example docstash UNIX SCCS automation (Bourne Shell) docstash.com VMS CMS automation (DCL) macros.h Example used in sample C function library haspriv.c Example used in sample C function library insert.mar Example used in sample C function library juldate.c Example used in sample C function library delstr.asm Example used in sample C function library c.txt C Standard Library on-line help transport file zero.c Example used in sample C function library UPDATE.DOC This is an optional file that contains updates to the printed DOCZ User Manual. If supplied, it will be deposited in the DOCREF directory during installation. 143 INSTALLATION MSDOS VERSION MSDOS Version Minimum Requirements o You must run MSDOS version 2.0 or higher and have at least 256k of memory. Getting Started with the MSDOS Version (1) Send in the Registration (2) Copy the distribution media, and run the INSTALL program with the disk containing the INSTALL program as the default device. (3) Answer the questions provided by the installation program. (4) Please read the User Manual before calling Software Toolz with questions. MSDOS Version Installation Procedure The Installation Program, INSTALL.EXE, will perform all necessary steps for the installation of DOCZ, or you may choose to customize the installation yourself. In any event, you should run the Installation Program first as it performs a test on your MSDOS system for adequate memory and system parameters. The Installation Program features extensive help messages that will guide you through an installation. The installation is self-explanatory and will not be documented here. DOCZ requires that two directories be set aside for use by the DOC programs. These directories will be used to store the Documentation Index File, and may be used to store all or some of your source files containing module documentation. You can establish where those directories are in either of two ways: (1) Create directories named \DOCSRC and \DOCREF on the device that you wish to use the DOCZ directories. (2) Use any directories of your choice and equate the CLI (command-language-interpreter) symbol, DOCSRC to the directory name of the default source directory and DOCREF to the name of the Documentation Reference Directory. In your AUTOEXEC.BAT, you would add the lines, 144 INSTALLATION SET DOCSRC=<directory name> SET DOCREF=<directory name> For example: SET DOCSRC=C:\LIBRARY\SOURCE SET DOCREF=C:\LIBRARY\INDEX There will be one sub-directory to the Default Source Directory (DOCSRC) per library, and the name of the sub- directory will be the same as the name of the library. When defining CLI symbols, insure that your system has sufficient "environment space." Later versions of MSDOS allow increasing the environment space via an option in CONFIG.SYS. Earlier versions of MSDOS can achieve this only through patching of COMMAND.COM. DOCZ programs currently limit the number of modules allowed in a single library to approximately 1000. The maximum number of modules that your system memory allows is displayed when you run the DOC program. This limitation is established to allow DOCZ to run on a PC with only 256k of memory. Note that this limitation applies only to the number of modules in one library. There is no theoretical limit on the total number of modules that may be contained in the Documentation Index and no limit on the number of libraries you may choose to use. The bldocz.bat command file is provided to build the sample CSUB library from the sample sources. Files in a Working MSDOS DOCZ System DOC.EXE DOC program DOCXL.EXE DOCXL program DOCXLU.EXE Documentation Index File utility DOCXLED.EXE DOCXLED program DOCHBLD.EXE Help library build utility DOCHELP.EXE On-line help program DOCGET.EXE DOCZ source file parameter retrieval DOCLOG.EXE DOCZ log examination utility DOCLIS.EXE Source file scanning utility DOCMAN.EXE DOCZ on-line User Manual DOCLEARN.EXE DOCZ on-line tutorial CALCDATE.EXE Date calculation utility FILLS.EXE Space/tab file test utility RETAB.EXE Convert spaces to tabs utility DETAB.EXE Convert tabs to spaces utility 145 INSTALLATION PSET.EXE PSET utility for printer interface SSORT.EXE SORT utility used by DOC DOCZ_SYM.BAT defines DOCZ environment symbols PSET.DAT printer database produced by PCODE and maintained by the PSET utility %DOCREF%DOCXL.DAT the Documentation Index produced by the DOCXL program %DOCREF%DOCZ.CFG the optional DOCZ Configuration File %DOCREF%DOCHELP.HLP on-line help library for DOCHELP %DOCSRC%BLDOCZ.BAT ds the sample library buil If installation of the examples is selected during the installation procedure, the examples are copied to the DOCSRC directory. 146 INSTALLATION VMS VERSION VMS Version Minimum Requirements o You must run VMS version 4.5 or higher. o VAXCRTL run-time library is required (furnished with 4.4 and later). Getting Started with the VMS Version (1) Send in the Registration (2) Run the VMS installation command file, VMSINSTAL (3) Answer the questions provided by the installation kit. (4) Please read the User Manual before calling Software Toolz with questions. VMS Version Installation Procedure The Installation Procedure will perform all necessary steps for the installation of DOCZ, or you may choose to customize the installation yourself. To perform a DOCZ installation, run VMSINSTAL with the distribution media inserted in device: @SYS$UPDATE:VMSINSTAL DOCZ016 <device name> This installation should be performed by the System Manager of the VAX on which you plan to install DOCZ. The procedure is self-explanatory, and installing DOCZ is trivial if you are satisfied by the defaults provided by the installation procedure. The only question asked by the procedure is the device on which DOCZ directories will be created. The default for this device is $DISK1 (logical name), which is the system disk in some VMS systems. A logical name may be used for this device, but it must be a permanent logical name. 147 INSTALLATION DOCZ requires that three directories be set aside for use by the DOC programs. One will be used as the Default Source Directory serving a the root directory to sub-directories containing source files with module documentation, another will contain the Documentation Index File and other reference files, and the third will be used to contain several data files used by DOCZ. Technically, the three directories may be the same physical directory, except when is used to control the source code. The installation CMS procedure will create the required directories for you. Three logical names must be declared that will point to the three directories required: There will be one sub-directory to the Default Source Directory per library, and the name of the sub-directory will be the same as the name of the library. DOCSRC default source directory DOCREF directory to contain reference files used by DOCZ DOCDAT data files for use by DOC These logical names should not be rooted. These may be permanent or process logical names, but must be defined for the users of DOCZ. The installation procedure generates a command file, SYS$MANAGER:DOCZ_LOGIN.COM, that defines the logical names as process logical names and defines the DOCZ program names as DCL foreign commands. This command file could be provided for DOCZ users in any of three ways: (1) Calling SYS$MANAGER:DOCZ_LOGIN from SYS$SYLOGIN, which will define DOCZ symbols and logical names for all users who log in. (2) Instruct user to call SYS$MANAGER:DOCZ_LOGIN from their own SYS$LOGIN:LOGIN.COM. (3) Modify DOCZ users' UAF, so that LGICMD=SYS$MANAGER:DOCZ_LOGIN. If this method is chosen, do not forget to add: $ IF F$SEARCH("SYS$LOGIN:LOGIN.COM") .EQS. "" THEN EXIT $ @SYS$LOGIN:LOGIN $ EXIT to SYS$MANAGER:DOCZ_LOGIN.COM so that the user's LOGIN.COM will be run before DOCZ_LOGIN exits. The installation procedure does not make any of the above modifications: this step requires a manual change that will have to be made by the VMS system administrator. 148 INSTALLATION The installation procedure also creates a start-up file, SYS$MANAGER:DOCZ_STARTUP.COM, which must be called from your system start-up procedure (SYSTARTUP.COM in pre-version 5 VMS, and SYSTARTUP_V5.COM in post-version 5 VMS). The installation procedure does not attempt to modify the system start-up: this step requires a manual change that will have to be made by the system administrator. The provision to allow CMS (Code Management System) to manage the code has been built-in to DOCZ. If CMS is installed on your VAX, the installation procedure will detect its presence and link the DOCZ programs to it. See also "OTHER FEATURES: Directory Layout." DOCZ programs currently limit the number of modules allowed in a single library to 1024. This limitation is established merely to assume a reasonable maximum for purposes of memory allocation. Note that this limitation applies only to the number of modules in one library. There is no theoretical limit on the total number of modules that may be contained in the Documentation Index and no limit on the number of libraries you choose to use. The DOCXL and DOCXLU programs must be installed with the SYSLCK privilege as they take out an exclusive write system- wide lock using the VMS lock manager facility. This installation will be performed by SYS$MANAGER:DOCZ_STARTUP.COM. None of the other DOCZ programs need be installed with privileges. Any of the DOCZ programs may be installed SHARED. If DOCZ is installed on a VMS system not having CMS, and CMS is installed at a later time; the DOCZ System must be reinstalled to be able to make use of CMS. A re- installation will not effect any DOCZ files built by your DOCZ System modified or created since an earlier installation (Documentation Index File, error log, etc.). Files in a Working VMS DOCZ System SYS$SYSTEM:DOC.EXE DOC program SYS$SYSTEM:DOCXL.EXE DOCXL program SYS$SYSTEM:PCODE.EXE the PCODE utility SYS$SYSTEM:DOCXLU.EXE Documentation Index File utility SYS$SYSTEM:DOCXLED.EXE DOCXLED utility program SYS$SYSTEM:DOCHBLD.EXE Help library build utility SYS$SYSTEM:DOCHELP.EXE On-line help program SYS$SYSTEM:DOCGET.EXE DOCZ source file parameter retrieval 149 INSTALLATION SYS$SYSTEM:DOCLOG.EXE DOCZ log examination utility SYS$SYSTEM:DOCLIS.EXE Source file scanning utility SYS$SYSTEM:DOCMAN.EXE DOCZ on-line User Manual SYS$SYSTEM:DOCLEARN.EXE DOCZ on-line tutorial SYS$SYSTEM:CALCDATE.EXE Date calculation utility SYS$SYSTEM:FILLS.EXE Space/tab file test utility SYS$SYSTEM:RETAB.EXE Convert spaces to tabs utility SYS$SYSTEM:DETAB.EXE Convert tabs to spaces utility SYS$SYSTEM:PSET.EXE PSET utility for printer interface DOCDAT:BANNER.DAT font file for banners printed on the documentation DOCDAT:PCODE.DAT printer database for PCODE DOCDAT:PSET.DAT printer database produced by PCODE and maintained by the PSET utility DOCREF:DOCXL.DAT the Documentation Index produced by the DOCXL program DOCREF:DOCZ.CFG the optional DOCZ Configuration File DOCREF:DOCHELP.HLP On-line help file for DOCHELP The examples are copied to the SYS$EXAMPLES directory. 150 INSTALLATION UNIX VERSION UNIX Version Minimum Requirements o You must run UNIX System V, version 3 or higher. Getting Started with the UNIX Version (1) Send in the Registration (2) Run the Unix installation script (3) Answer the questions provided by the Installation Kit. (4) Please read the User Manual before calling Software Toolz with questions. UNIX Version Installation Procedure Whenever possible, the DOCZ System installation kit will support the automated installation facility provided by the native Unix system. For those Unixes that do not provide an automated installation facility, the DOCZ installation procedure will accompany the distribution media. The Installation Procedure will perform all necessary steps for the installation of DOCZ, or you may choose to customize the installation yourself. The procedure does not require root privileges unless you wish to place the DOCZ files in system directories which have protection. The installation procedure will ask for the names of directories into which the DOCZ files will be placed. If the directories do not already exist, they will be created. Default standard Unix directory names are supplied, but the installer may specify any directory name. If the DOCZ installation will overwrite any files with the same names as DOCZ files, those files currently on the system are moved to /usr/tmp. DOCZ requires that two directories be set aside for use by the DOCZ programs. One will be used as the default directory for the storage of source files containing module documentation, another will contain the Documentation Index File and other reference files. Technically, the directories may be the same physical directory. The installation procedure will create the required directories for you. 151 INSTALLATION You can establish where those directories are in either of two ways: (1) directories named ../docsrc and ../docref Create parallel to your working directory. (2) (Recommended) Use any directories of your choice and equate the CLI (command-language-interpreter) symbol, DOCSRC to the directory name of the Default Source Directory, DOCREF to the name of the Documentation Reference Directory. The symbols may point to the same directory. In your .profile or /etc/profile, you would add the lines, DOCSRC=<directory name> DOCREF=<directory name> export DOCSRC DOCREF For example: DOCSRC=/usr/program/source DOCREF=/usr/program/index export DOCSRC DOCREF There will be one sub-directory to the Default Source Directory per library, and the name of the sub-directory will be the same as the name of the library (in upper case). DOCZ programs currently limit the number of modules allowed in a single library to 1024. This limitation is established merely to assume a reasonable maximum for purposes of memory allocation. Note that this limitation applies only to the number of modules in one library. There is no theoretical limit on the total number of modules that may be contained in the Documentation Index and no limit on the number of libraries you choose to use. The bldocz script is provided to build the sample CSUB library from the sample sources. 152 INSTALLATION Files in a Working UNIX DOCZ System doc DOC program docxl DOCXL program pcode the PCODE utility pset PSET utility for printer interface docxlu Documentation Index File utility docxled DOCXLED utility program dochbld Help library build utility dochelp On-line help program docget DOCZ source file parameter retrieval doclog DOCZ log examination utility doclis Source file scanning utility docman DOCZ on-line User Manual doclearn DOCZ on-line tutorial calcdate Date calculation utility fills Space/tab file test utility retab Convert spaces to tabs utility detab Convert tabs to spaces utility docz_sym defines DOCZ environment symbols BANNER.DAT font file for banners printed on the documentation PCODE.DAT printer database for PCODE PSET.DAT printer database produced by PCODE and maintained by the PSET utility $DOCREF/DOCXL.DAT the Documentation Index produced by the DOCXL program $DOCREF/DOCZ.CFG the optional DOCZ Configuration File $DOCREF/DOCHELP.HLP On-line help file for DOCHELP $DOCSRC/bldocz builds the sample library If installation of the examples is selected during the installation procedure, the examples are copied to the DOCSRC directory. 153 INDEX $STATUS, 21 .APPLICATION parameter, 30 .ARGUMENTS parameter, 30 .AUTHOR parameter, 30 .CAUTION parameter, 31 .COMMENTS parameter, 31 .CONVENTIONS parameter, 33 .DESCRIPTION parameter, 29 .DIAGRAM parameter, 33 .ENDOC parameter, 27, 33 .ERRORS parameter, 33 .FIXES parameter, 27, 31 .INCLUDES parameter, 33 .LANGUAGE parameter, 32, 33 .LIBRARY parameter, 27, 29 .LSE parameter, 32 .MODULE parameter, 27, 29 .NARRATIVE parameter, 30 .NOTICE parameter, 32 .OVERHEAD parameter, 31 .REFERENCES parameter, 32 .RETURNS parameter, 32 .REVISION parameter, 27, 31 .SEE_ALSO parameter, 32 .SYSTEM parameter, 30 .TYPE parameter, 29 alternate directories, 57 ambiguous file names, 19 ASCII transport files, 21, 73, 77, 95 batch files, 20 building documentation libraries, 37 CALCDATE, 99 case, 21, 25, 29, 30, 38, 50, 54, 56, 85, 115, 154 case, as applied in file names, 20 case, as applied in names, 25, 27, 134 case, in date specifications, 24 CLI symbols, 147 CMS, 12, 37, 74, 116, 117, 123, 127, 134, 150, 151 command files, 20 Command-line options, 60 comment string mask, 27, 53, 54 Configuration File, 26, 49, 52, 53, 55, 57, 74, 98, 111, 144, 147, 151, 155 control keys, 23 cross-platform development, 12, 118, 136, 144 cross-platform file specification translation, 118 data directory, 37, 50, 98, 109, 150, 153 155 INDEX date format, 23, 43, 99, 108, 109 dates, change notice, 45 dates, current format, 99 dates, default format, 23, 99 dates, fix notice, 43 dates, introduction, 63 dates, modification, 63 dates, revision notice, 43 default source directory, 15, 37, 38, 146, 150, 153 defaults, overriding, 57 DETAB, 103 DOCDAT, 15, 37, 94, 150 DOCGET, 85 DOCHBLD, 77 DOCHELP, 79 DOCLEARN, 91 DOCLIS, 86 DOCLOG, 88 DOCMAN, 90 DOCREF, 146, 150, 154 DOCSRC, 38, 116, 117, 134, 146, 150, 154 documentation data directory, 15 documentation header, 26, 28, 37, 41, 43 Documentation Index File, 26, 37, 118 documentation reference directory, 15, 42, 77, 107, 150, 153 documentation size, 134 DOCXLED, 81 DOCZ concepts, 11 enabling extended features, 144 Enter and Press, differences, 23 error level, 55 error levels, severity, 55 ERRORLEVEL, 21 example files, 145 File formats, 21 file name, maximum length, 25 file specifications, default, 117 FILLS, 102 formatting source code, 27 help, libraries, 120 help, on-line, 120 installation, MSDOS, 146 installation, UNIX, 153 installation, VMS, 149 library introduction, 41, 42, 45 library name, maximum length, 25 library names, maximum number of, 26 library summary, 45 logging, 55, 89, 124 156 INDEX logging, error, 55 logging, transaction, 55 logical names, 150 module deletion, 64 module name, maximum length, 25 multiple language support, 53 naming conflicts, module names, 39 number of modules, maximum, 147, 151 parameter, 26, 27, 28, 41, 43, 54, 106, 111, 114, 123, 146 parameter usage, 29 parameters, 113 parameters, multiple, 29 parameters, optional, 29 parameters, required, 29 parameters, single, 29 PCODE, 97 portability, 136 printer features, installing, 94, 97 printers, use by DOCZ System, 42 program directory, 15 PSET, 93 Record format, Documentation Index File, 133 REFORMAT, 100 RETAB, 104 return values, from programs, 21 SCCS, 12, 124, 127, 134 Shell, 86 shell scripts, 20 single module documentation, 47 sort programs, requirements, 76 Standard error, 134 summary, application keyword, 41, 45 summary, description permutations, 41, 45 summary, module description, 41, 45 summary, operating system platform, 41, 45 summary, quick description, 41, 45 support files, 145 switch character, 19 symbol substitution, 38, 118 tab character expansion, 27, 53, 54, 100, 102, 103, 104 text data file, 21 title page, 45 UNIX, 153 username, emulating in MSDOS, 59 utilizing printer features, 49 version control, 12, 37, 49, 57, 86, 115, 121, 124, 144 157 INDEX version control, command file automation, 127 version control, custom interface, 134 version numbers, 21 VMS, 149 wildcard, 19, 38, 79, 86 working directory, 15, 77, 94, 149 158